Live Demo: https://counterscarp.io — Official beta instance
- Overview
- Accessing the Web UI
- Upload Flow Walkthrough
- Understanding the Results Page
- Downloading Reports
- Attack Graph Visualization
- User Authentication
- Per-User License Management
- Admin Dashboard
- API Endpoints Reference
- API Rate Limiting
- CORS Policy
The Counterscarp Engine web application provides a browser-based interface for running security audits on smart contracts. Upload .sol or .rs files, run a full analysis pipeline, and view results with risk scoring, severity breakdowns, and AI-powered insights — all without the CLI.
The web app is built with FastAPI and runs on uvicorn, supporting both local development and production deployment behind nginx.
pip install "counterscarp-engine[web]"
uvicorn webapp.main:app --reload --port 8001Open http://localhost:8001 in your browser.
The official beta instance is available at https://counterscarp.io.
This is the live production deployment where you can:
- Upload and audit smart contracts without any local installation
- Generate professional security reports
- Explore interactive attack graphs
- Download findings in multiple formats (HTML, Markdown, SARIF, JSON)
See the Deployment Guide for instructions on setting up your own instance.
- Open the upload page — Navigate to the root URL (
/) - Enter project name — Provide a descriptive name for the audit (e.g., "MyProtocol V2")
- Select files — Click to browse or drag-and-drop
.solor.rsfiles- Maximum file size: 10 MB per file
- Supported formats: individual
.sol(Solidity) or.rs(Rust/Anchor) source files — ZIP archives are not currently supported - To upload a multi-file project, select all source files at once using your OS file picker (Ctrl+click or Shift+click)
- Click "Run Audit" — The analysis pipeline starts immediately
- Wait for results — You'll be redirected to the results page when complete (120-second timeout for web uploads)
Upload all related contract files together in a single submission. The engine analyses the full file set as one project, enabling detection of:
- Cross-contract reentrancy — attack paths that span multiple contracts
- Shared state issues — storage variables and proxy patterns across inheritance hierarchies
- Inter-contract access control — privilege escalation paths through delegatecall chains
Uploading contracts in separate sessions creates isolated audits and will miss vulnerabilities that only emerge from contract interactions.
| Constraint | Limit |
|---|---|
| Max file size | 10 MB per file |
| Scan timeout | 120 seconds |
| Supported formats | .sol (Solidity) and .rs (Rust/Anchor) source files |
The results page at /results/{audit_id} provides a comprehensive view of the audit findings.
The scan coverage panel shows which analyzers ran and how many patterns they checked:
| Analyzer | What It Shows |
|---|---|
| Heuristic Pattern Scanner | Number of patterns checked per category, findings count |
| Slither Static Analysis | Status (completed / not_installed / timeout / error), findings count |
| AI Audit Copilot | Status (completed / error / skipped) |
| Attack Graph Generator | Status (completed / skipped) |
The risk score is calculated on a 0-100 scale using weighted severity counts:
| Score Range | Status | Meaning |
|---|---|---|
| 0-19 | PASS | No significant issues detected |
| 20-39 | PASS / WARNING | Low-risk findings only |
| 40-69 | WARNING | High-severity findings present |
| 70-100 | FAIL | Critical or multiple high findings |
Weighting formula:
- CRITICAL = 10.0 points
- HIGH = 5.0 points
- MEDIUM = 2.0 points
- LOW = 0.5 points
- INFO = 0.1 points
The severity breakdown shows the count of findings at each level:
| Severity | Color | Typical Impact |
|---|---|---|
| CRITICAL | Red | Exploitable vulnerabilities leading to direct fund loss |
| HIGH | Orange | Serious vulnerabilities requiring immediate attention |
| MEDIUM | Yellow | Issues that could become exploitable under specific conditions |
| LOW | Blue | Minor issues or best practice violations |
| INFO | Gray | Informational findings, no direct security impact |
When the AI Audit Copilot is available, it provides:
- Similarity search — Matches current findings against the RAG knowledge base of known vulnerabilities
- Remediation guidance — Suggests fixes based on historical patterns
- Context enrichment — Adds relevant references and CWE classifications
Note: The AI Copilot uses local sentence-transformers embeddings by default. No API keys are required. Install with pip install "counterscarp-engine[ai]".
Each scan creates an isolated output directory so multiple scans of the same project never overwrite each other:
reports/{ProjectName}_{YYYY-MM-DD}_{session}/
├── audit_report.md
├── audit_report.html
├── ACTION_PLAN.md
├── scan.log
└── exploits/ ← Exploit PoC files (Pro+ only)
{ProjectName}is the name entered at upload time{YYYY-MM-DD}is the scan date{session}is a short unique identifier for the run
Running the same project on different days (or multiple times in a day) creates separate directories; no results are overwritten.
When scanning with a Pro (or higher) license, the results page includes auto-generated Foundry exploit test files for critical and high-severity findings.
- Each CRITICAL or HIGH finding includes a link to a
.t.solFoundry test that demonstrates the attack vector - The test file is runnable with
forge testagainst a local Anvil fork — no manual scaffolding required - Individual PoC files can be downloaded from the finding detail panel, or you can download the full
exploits/directory as a ZIP from the results page footer - Exploit PoCs are stored in the
exploits/subdirectory within the per-scan report folder
Requirements: Foundry must be installed locally to execute the generated tests. See foundry.paradigm.xyz for installation instructions.
Four report formats are available for download from the results page:
| Format | URL Pattern | Content Type |
|---|---|---|
| HTML | /results/{id}/report/html |
text/html |
| Markdown | /results/{id}/report/md |
text/markdown |
| SARIF | /results/{id}/report/sarif |
application/json |
| JSON | /results/{id}/report/json |
application/json |
For detailed information about each format, see the Report Formats Guide.
The attack graph is an interactive D3.js visualization that shows:
- Contract structure — Functions, state variables, and their relationships
- Attack paths — How findings connect through external calls and state changes
- Severity mapping — Color-coded nodes indicating vulnerability severity
- Interactive exploration — Click to expand/collapse nodes and trace paths
Access the attack graph at: /results/{audit_id}/attack-graph
The attack graph is generated automatically when findings are detected. If no findings exist, the graph is skipped.
Configuration: Attack graph behavior can be customized in scarpshield.toml (or legacy counterscarp.toml) under the [visualization] section. See the Configuration Guide for details.
The web application supports two authentication methods:
Google OAuth 2.0:
- Click "Sign in with Google" on the login page
- First-time users are automatically registered
- Uses OpenID Connect for secure token exchange
Email/Password:
- Register at
/auth/registerwith name, email, and password - Passwords are hashed with bcrypt
- Log in at
/auth/login
Licenses are linked to individual user accounts:
- Automatic linking at purchase: When a logged-in user completes a Stripe checkout, their license is automatically linked to their account
- Automatic linking at registration: If a user purchases before creating an account, the license is automatically discovered and linked when they register with the same email
- Manual activation: Users can enter a license key manually on the Settings page
- Cross-device: Licenses persist with the account and activate on login from any device
The /admin/users endpoint (JSON API) is restricted to the configured ADMIN_EMAIL and returns:
- User list with email, name, auth method, registration date, last login
- License key (masked) and current tier for each user
Authentication required: /api/license/info requires an active session and the logged-in user's email must match the ADMIN_EMAIL environment variable. All other authenticated users receive 403 Forbidden.
Upload page (HTML form).
Run a security audit on uploaded files.
Request: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
project_name |
string | Yes | Name for the audit |
files |
File[] | Yes | .sol or .rs files (max 10 MB each) |
Response: Redirects to /results/{audit_id} (303).
Errors:
| Status | Condition |
|---|---|
| 400 | No files uploaded |
| 400 | Invalid file type (not .sol or .rs) |
| 400 | File exceeds 10 MB limit |
Display audit results page.
Response: HTML page with findings, risk score, severity breakdown, and download links.
Errors:
| Status | Condition |
|---|---|
| 404 | Audit ID not found |
Download a report file.
Format options: html, md, sarif, json
Response: File download with appropriate content type.
Errors:
| Status | Condition |
|---|---|
| 400 | Invalid format |
| 404 | Report file not found |
View the interactive attack graph visualization.
Response: HTML page with embedded D3.js graph.
Errors:
| Status | Condition |
|---|---|
| 404 | Attack graph not generated (no findings or generation failed) |
Health check endpoint.
Response:
{
"status": "ok",
"timestamp": "2024-01-15T10:30:00.000000"
}Rate limiting is enforced per IP address on license and webhook endpoints to protect against abuse.
| Endpoint | Method | Limit |
|---|---|---|
/api/license/validate |
POST | 10 requests per minute |
/api/license/deactivate |
POST | 5 requests per minute |
/api/stripe/webhook |
POST | 30 requests per minute |
Response when exceeded: HTTP 429
{"detail": "Rate limit exceeded. Try again later."}Rate limit windows reset after 60 seconds. If you are hitting limits from a CI/CD pipeline, consider caching validation results locally rather than re-validating on every run.
The API accepts cross-origin requests only from the following origins:
https://app.counterscarp.iohttps://counterscarp.iohttp://localhost(any port, for local development)
Requests from any other origin are rejected with HTTP 403. If you are self-hosting and need to add a custom origin, configure the ALLOWED_ORIGINS environment variable before starting the server.
Counterscarp Security Engine • counterscarp.io