Getting Started

Getting Started with Counterscarp Engine

Try it online: https://app.counterscarp.io — Run audits in your browser, no installation required.

---

Installation

PyPI Package

Counterscarp Engine is available on PyPI: https://pypi.org/project/counterscarp-engine/

Requirements:

• Python 3.10+ (3.10, 3.11, or 3.12)
• pip package manager

Core Installation

pip install counterscarp-engine

Installation with Optional Features

# Web UI (FastAPI + uvicorn)
pip install "counterscarp-engine[web]"

# AI/RAG enrichment (local embeddings, no API needed)
pip install "counterscarp-engine[ai]"

# Everything at once
pip install "counterscarp-engine[web,ai]"

# Development dependencies (pytest, mypy, benchmarks)
pip install "counterscarp-engine[dev]"

Docker Installation

# Build image
docker build -t counterscarp-engine .

# Run audit
docker run --rm -v $(pwd):/scan counterscarp-engine --target /scan

Verify Installation

counterscarp --help
# or
counterscarp-engine --help

Tip: The counterscarp and counterscarp-engine commands are interchangeable aliases.

---

Optional Dependencies

For full functionality, install these external tools:

Slither (Static Analysis)

pip install slither-analyzer
solc-select install 0.8.19
solc-select use 0.8.19

Aderyn (Rust-based Analyzer)

cargo install aderyn

Medusa (Fuzzing)

go install github.com/crytic/medusa/cmd/medusa@latest

Mythril (Symbolic Execution)

pip install mythril

Foundry

curl -L https://foundry.paradigm.xyz | bash
foundryup

---

First Audit in 60 Seconds

1. Scan a Solidity project

counterscarp --target ./contracts

This runs the default pipeline: heuristic pattern scan + Slither static analysis + supply chain check.

2. Generate a professional report

counterscarp --target ./contracts --report --project-name "MyProtocol"

This produces both an HTML and Markdown audit report with risk scoring.

3. Use a config file

counterscarp --target ./contracts --config counterscarp.toml

Create a counterscarp.toml in your project root to customize rules, suppressions, and analysis behavior. See the Configuration guide for the full reference.

Minimal Config Example

[engine]
name = "MyProtocol Audit"
fail_on_severity = "HIGH"

[heuristics]
enabled = true

---

Understanding Output

Output locations:

• Console: Immediate findings printed to terminal
• File: ACTION_PLAN_YYYYMMDD_HHMMSS.md in your scanned directory
• Reports: audit_report_*.html and audit_report_*.md (with --report flag)

Example report structure:

# SECURITY AUDIT REPORT

## Executive Summary
- **Critical:** 2 findings
- **High:** 5 findings  
- **Medium:** 12 findings

## Heuristic Scanner
[CRITICAL] UNCHECKED_EXTERNAL_CALL (Line 142)
  • External call without return value check
  • FIX: Wrap in require() or check success boolean

## Liar Detector
[MISMATCH] Line 67: emergencyWithdraw
  • Comment says "admin" but function is public with NO modifier
  • FIX: Add onlyOwner modifier

---

Pro License Activation

Counterscarp Engine ships with both free and pro features in a single package. Pro features require a valid license key to unlock.

Setting Your License Key

Option 1: Environment variable

export COUNTERSCARP_PRO_LICENSE=GE-PRO-XXXXXXXXXXXX

Option 2: Configuration file

Add a [license] section to your counterscarp.toml:

[license]
key = "GE-PRO-XXXXXXXXXXXX"

The environment variable takes priority over the config file.

---

Tier Overview

Counterscarp Engine offers five license tiers:

Tier	Price	Key Prefix	Features
Community	Free	—	Core heuristic scanner, Slither, basic reports (Markdown/JSON), CLI
Developer	$49/mo	GE-DEV-xxx	Web app, Solana Analyzer, HTML/SARIF reports
Pro	$199/mo	GE-PRO-xxx	AI Copilot, Attack Graph, Exploit PoC, Time-Travel, Fingerprinting
Team	$399/mo	GE-TEAM-xxx	5 seats, shared workspace, API access
Enterprise	Custom	GE-ENT-xxx	Unlimited seats, custom integrations, priority support

Tier Features

Developer tier unlocks:

• Web App — Full web-based audit interface at app.counterscarp.io
• Solana Analyzer — 35 Rust/Anchor security patterns with IDL validation
• Branded HTML/SARIF Reports — Professional branded audit report output

Pro tier unlocks (includes all Developer features):

• AI Audit Copilot — RAG-based vulnerability explanations and remediation guidance
• Attack Graph Visualization — Interactive D3.js cross-contract attack path graphs
• Exploit PoC Generator — Automatic Foundry exploit test case generation
• Time-Travel Scanner — Git-based historical vulnerability tracking
• Protocol Fingerprinting — Protocol similarity and inherited vulnerability detection

Team tier unlocks (includes all Pro features):

• 5 Seats — Shared team access with centralized management
• Shared Workspace — Collaborative audit projects and findings
• API Access — Programmatic integration with CI/CD pipelines

Getting a License

Visit app.counterscarp.io/pricing to purchase a Developer, Pro, Team, or Enterprise license.

---

Next Steps

Guide	Description
CLI Reference	All commands, flags, profiles, and exit codes
Configuration	Full counterscarp.toml reference with examples
Web App Guide	Web UI features and API endpoints
Deployment	Production server setup with nginx + SSL

---

Counterscarp Engine • counterscarp.io