Documentation

Quick Start

Get Counterscarp running quickly with the following steps.

Getting Started Workflow

Use this path for your first production-ready rollout from install to CI.

1. Install: pip install counterscarp-engine
2. Run first scan: counterscarp scan ./contracts --config counterscarp-pr.toml
3. Interpret report: review severity, file path, line number, and remediation notes before suppressing anything.
4. Suppress noise safely: add targeted inline suppressions or config suppressions for known false positives only.
5. Integrate CI/CD: start with PR profile, then run full audit on merges/releases.

Installation

Core Installation

Optional Tools

Pro License Activation

Licenses are tied to machine activations. Keys are cached offline for 24 hours after first validation.

Manage your license, view activation status, and update settings at app.counterscarp.io/settings

Webapp vs CLI

Counterscarp is available as both a cloud-hosted Webapp at app.counterscarp.io and a local CLI tool. All plans include access to both. Here's what each offers:

First Audit

Option 1: GUI (Easiest)

Option 2: CLI (Professional)

Configuration Files

Counterscarp uses TOML configuration files to control analyzer behavior, severity thresholds, and output formats.

# Counterscarp — Full Audit Configuration

[project]
name = "MyDeFi Protocol"
version = "5.1.1"

[analyzers]
slither     = true
aderyn      = true
mythril     = true
ai_copilot  = true
attack_path = true
time_travel = true

[thresholds]
blocker_severity = "HIGH"
max_findings     = 0  # 0 = fail on any HIGH

[output]
html_report = true
md_report   = true
json_output = false

Suppressions

Use suppressions only for reviewed false positives. Keep scope narrow and document why each suppression exists.

Inline suppression

function sweep(address to) external onlyOwner {
    // counterscarp-suppress:OWNER-WITHDRAW
    token.transfer(to, token.balanceOf(address(this)));
}

Config suppression (counterscarp.toml)

[suppressions]
rules = ["LOW-LEVEL-CALL", "TIMESTAMP-DEPENDENCE"]
paths = ["contracts/mocks/**", "test/**"]

[suppressions.notes]
LOW-LEVEL-CALL = "Intentional proxy delegatecall in reviewed module"
TIMESTAMP-DEPENDENCE = "Used only for UI cooldown display"

Audit Profiles

Profile Commands

CLI Reference

CI/CD Integration

Counterscarp integrates with all major CI/CD platforms. Use the auto-generator or copy the manual snippets below.

Auto-Generate Pipeline Config

GitHub Actions (Manual)

name: Counterscarp Audit
on:
  pull_request:
    branches: [main]

jobs:
  blocker-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Counterscarp
        run: pip install counterscarp-engine --upgrade
      - name: Counterscarp PR Check (Blockers)
        env:
          COUNTERSCARP_PRO_LICENSE: ${{ secrets.COUNTERSCARP_PRO_LICENSE }}
        run: |
          counterscarp scan ./contracts \
            --config counterscarp-pr.toml
  advisory-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Counterscarp
        run: pip install counterscarp-engine --upgrade
      - name: Counterscarp Full Audit
        env:
          COUNTERSCARP_PRO_LICENSE: ${{ secrets.COUNTERSCARP_PRO_LICENSE }}
        run: |
          counterscarp scan ./contracts \
            --config counterscarp-audit.toml \
            --report

GitLab CI (Manual)

counterscarp-engine:
  stage: test
  image: python:3.11
  variables:
    COUNTERSCARP_PRO_LICENSE: ${COUNTERSCARP_PRO_LICENSE}
  script:
    - pip install counterscarp-engine --upgrade
    - counterscarp scan ./contracts --config counterscarp-pr.toml
  only:
    - merge_requests

Azure DevOps (Manual)

trigger:
  branches:
    include: [main]

pool:
  vmImage: ubuntu-latest

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.11'
- script: pip install counterscarp-engine --upgrade
  displayName: 'Install Counterscarp'
- script: counterscarp scan ./contracts --config counterscarp-pr.toml
  displayName: 'Counterscarp Scan'
  env:
    COUNTERSCARP_PRO_LICENSE: $(COUNTERSCARP_PRO_LICENSE)

Jenkins (Manual)

pipeline {
  agent { label 'python' }
  environment {
    COUNTERSCARP_PRO_LICENSE = credentials('counterscarp-pro-license')
  }
  stages {
    stage('Security Scan') {
      steps {
        sh 'pip install counterscarp-engine --upgrade'
        sh 'counterscarp scan ./contracts --config counterscarp-pr.toml'
      }
    }
  }
}

API Reference

Counterscarp exposes a Python API for programmatic integration.

from counterscarp import CounterscarpEngine, AuditConfig

# Initialize engine
engine = CounterscarpEngine(
    config=AuditConfig.from_file("counterscarp-audit.toml")
)

# Run audit
results = engine.audit(target="./contracts")

# Access findings
for finding in results.findings:
    print(f"{finding.severity}: {finding.title}")
    print(f"  File: {finding.file}:{finding.line}")

# Generate report
results.export_html("audit_report.html")
results.export_markdown("audit_report.md")

Changelog

v5.1.1 — May 20, 2026 Latest

• Solana/Anchor Analyzer — complete implementation with 40 security patterns across 7 categories
• Full IDL validator integration — Anchor IDL constraint and CPI flow analysis
• 9 new Solana patterns: authority pubkey mismatch, missing multisig upgrade, unsafe narrowing cast, and more
• CLI: counterscarp --chain solana --solana-root /path/to/project
• Security hardening: block zero-credit PAYG users, require auth for scans, production config validation, thread-safe sessions
• Marketing honesty cleanup — removed false "zero false positives" claims, standardized analyzer counts

v5.0.7 — April 28, 2026

• Pay-As-You-Go scan packs — purchase 1, 5, or 15 scan credits without a subscription
• Atomic credit consumption with transactional deduction and automatic refund on failure
• TOTP recovery codes — ten single-use backup codes generated at 2FA enrollment
• Audit deletion — authorised users can permanently remove audit records
• Scan notifications — email and in-app alerts on scan completion

v5.0.6 — April 28, 2026

• Audit trail logging — append-only JSONL log for all license mutations
• Stripe webhook idempotency with Redis + file fallback for event deduplication
• Per-user audit dashboard at /dashboard
• Rate limit headers on all API and webhook endpoints
• Async job queue powered by arq for background scan processing
• TOTP two-factor authentication for user accounts
• Grace period notification banner for expiring licenses

v5.0.5 — April 23, 2026

• Orchestrator refactored into 15-phase registry architecture (H1)
• Async subprocess execution with concurrent phase groups (M6)
• Redis sliding-window rate limiter with in-memory fallback (M9)
• Trusted proxy validation for X-Forwarded-For headers
• Full mypy strict-mode compliance

v5.0.3 — April 23, 2026

• counterscarp --doctor CLI: environment diagnostic command checking all analyzer dependencies
• Multi-stage Docker image bundling the complete analyzer stack on Python 3.12
• docker-compose support with four service profiles: full audit, diagnostics, heuristic-only, symbolic execution
• Docker deployment documentation added to QUICKSTART.md, DEPLOYMENT.md, and wiki
• Landing page SEO title optimization
• Auto-detect Foundry projects via foundry.toml and exclude lib/** from scanning
• Parse foundry.toml custom out directory for Slither --foundry-out-directory
• Bump Slither and forge build timeouts from 300s to 600s for large Foundry projects

v5.0.2 — April 23, 2026

• Documentation version references synchronized across all pages and reports
• Fixed broken Foundry integration: resolved compilation failures for projects with via-ir and custom out directories

v5.0.1 — April 22, 2026

• Cloud App launched at app.counterscarp.io with Google OAuth authentication
• 5-tier licensing model: Community (free), Developer, Pro, Team, Enterprise
• Supply Chain Analysis, Time-Travel Git Scanner, and Protocol Fingerprinting analyzers
• Stripe payment integration with automatic license linking
• Published to PyPI: pip install counterscarp-engine --upgrade

v5.0.0 — April 21, 2026

• Account-based licensing with Google OAuth and email authentication
• Automatic license linking at Stripe checkout
• Published to PyPI: pip install counterscarp-engine --upgrade
• Python 3.9, 3.10, 3.11, 3.12 support confirmed
• Development Status: 5 - Production/Stable

v2.0.0 — February 2026

• 14 free analyzers, up to 21 with Pro — full EVM + Solana coverage
• 7 innovative features: AI Copilot, Attack Path Visualizer, Time-Travel Scanner, CI/CD Generator, Exploit Generator, Fingerprint Scanner, Anchor IDL Validator
• 940+ tests passing
• GUI + CLI interfaces
• Docker deployment support
• 3 execution profiles: PR / Audit / Bounty