Skip to content

FAQ

Jump to bottom
dev-mondoshawan edited this page Apr 21, 2026 · 3 revisions

Frequently Asked Questions

Common questions about Counterscarp Engine installation, usage, licensing, and troubleshooting.

General Questions

Is Counterscarp Engine free?

Yes! The Community tier is completely free and includes 14 analyzers:

  • Heuristic Scanner (31 EVM rules)
  • Slither integration
  • Liar Detector, Access Matrix, Upgrade Diff
  • Supply Chain Check, Threat Intel
  • Markdown/JSON reports
  • GUI and CLI access

Pro features require a paid license. See Pricing for details.

Does it support Solana?

Yes! The Solana Analyzer with 35 Rust/Anchor security patterns is available in the Developer tier and above. It includes:

  • 35 Anchor/Rust security rules
  • IDL constraint validation
  • CPI flow tracing
  • Account permission matrices

Can I use it commercially?

Yes! The Community tier is MIT licensed and can be used for commercial projects without restriction. Pro features have their own EULA but also allow commercial use.

Installation Issues

"Slither not found" error

Slither is optional but recommended. To install:

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

"Aderyn not found" error

Aderyn requires Rust. Install with:

cargo install aderyn

Or via Foundry:

foundryup

"solc version not installed" error

Install the Solidity compiler version your project uses:

pip install solc-select
solc-select install 0.8.19
solc-select use 0.8.19

Docker build fails

Common causes:

  • Docker daemon not running — Start Docker Desktop or the service
  • Insufficient disk space — Ensure ~600MB free
  • Network timeout — Try building with --no-cache 
docker build -t counterscarp-engine --no-cache .

Common Errors and Fixes

"Cannot find contract file"

  • Ensure the target path exists and is accessible
  • Use absolute paths or verify relative paths from your current directory
  • Check file permissions

Slither fails to compile

This is normal if:

  • Contract uses a newer Solidity version (install it with solc-select)
  • Missing dependencies (run from Foundry/Hardhat project root)

Workaround: Use modules that don't need compilation:

python heuristic_scanner.py ./contracts    # Regex-based (always works)
python intent_check.py ./contracts/Token.sol  # Comment parsing
python threat_intel.py ./contracts/Token.sol  # API-based

Permission denied errors

On Linux/Mac:

chmod +x scripts/*.sh

Check write permissions for output directories:

ls -la ./results

Docker Troubleshooting

Container exits immediately

Check logs:

docker logs $(docker ps -lq)

Volume mounting issues (Windows)

Use PowerShell syntax:

docker run --rm -v ${PWD}:/scan counterscarp-engine --target /scan

Out of memory during analysis

Increase Docker memory limit in Docker Desktop settings (recommended: 4GB+)

License and Activation Questions

How do I activate my Pro license?

Method 1: Environment variable

export COUNTERSCARP_PRO_LICENSE=your-key-here
counterscarp-engine --target ./contracts --rag

Method 2: Configuration file

[license]
key = "your-key-here"

Method 3: Web app settings

"License key invalid" error

  • Check for typos in the license key
  • Ensure the key hasn't expired
  • Verify you haven't exceeded machine activation limits
  • Contact contact@counterscarp.io

How do I deactivate a machine?

  1. Log into app.counterscarp.io
  2. Go to "License Management"
  3. Click "Deactivate" next to the machine
  4. Or email contact@counterscarp.io

Can I use my license on multiple machines?

Depends on your tier:

  • Developer: 1 machine
  • Pro: 3 machines
  • Team: 10 machines
  • Enterprise: Unlimited

What happens when my subscription expires?

The software reverts to Community tier. Pro features will display an upgrade prompt instead of executing. Your data and reports remain accessible.

Web App Questions

What file types can I upload?

  • .sol — Solidity smart contracts
  • .rs — Rust source files (Solana programs)
  • .json — IDL files (Anchor)

Maximum file size?

10 MB per upload. For larger projects, use the CLI:

counterscarp-engine --target ./large-project --report

Where are my reports stored?

Reports are stored temporarily on the server and can be downloaded for 7 days. After that, re-run the scan to generate new reports.

Is my code kept private?

Yes. Uploaded code is:

  • Never stored permanently
  • Only used for analysis during your session
  • Never shared with third parties
  • Never used to train AI models

Performance Tips for Large Codebases

Analysis is too slow

  1. Use PR Mode for quick checks:

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

  2. Exclude test files:

    [ci]
exclude_paths = ["test/", "tests/", "*.t.sol"]

  3. Disable slow analyzers:

    [static_analysis]
mythril.enabled = false

[fuzzing]
medusa.enabled = false

  4. Run in parallel (for CI/CD):

    jobs:
  counterscarp:
    strategy:
      matrix:
        shard: [1, 2, 3, 4]

Running out of memory

  • Increase system RAM or swap
  • Use Docker memory limits: --memory=8g
  • Process contracts in batches
  • Disable symbolic execution (Mythril uses significant RAM)

CI/CD Integration

GitHub Actions example

name: Security Scan
on: [pull_request]

jobs:
  counterscarp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Counterscarp Engine
        run: pip install counterscarp-engine
      - name: Run PR Check
        run: counterscarp-engine --target ./contracts --config counterscarp-pr.toml

GitLab CI example

counterscarp-scan:
  image: python:3.11
  script:
    - pip install counterscarp-engine
    - counterscarp-engine --target ./contracts --config counterscarp-pr.toml
  only:
    - merge_requests

Failing on specific severity

[engine]
fail_on_severity = "HIGH"  # Fail on HIGH and CRITICAL

Report and Output Questions

How do I generate HTML reports?

counterscarp-engine --target ./contracts --report

HTML reports require Developer tier or higher.

Can I customize the report logo?

Yes, pass the logo_path parameter:

from report_generator import generate_html_report
generate_html_report(report, "output.html", logo_path="assets/my_logo.png")

SARIF upload to GitHub Security

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: audit_report.sarif

Contributing and Development

How do I add a new rule?

See Contributing for the step-by-step guide. In brief:

  1. Edit heuristic_scanner.py
  2. Add a HeuristicRule to the RULES list
  3. Test with python heuristic_scanner.py /path/to/contracts
  4. Submit a PR

How do I create a plugin?

See Plugin-Development for the full guide. Create a file in .counterscarp/plugins/ with a register() function.

Running tests

pytest                    # All tests
pytest -v                # Verbose
pytest --cov=.           # With coverage
pytest tests/test_heuristic_scanner.py  # Specific file

Getting Help

Documentation

Support Channels

Tier Support
Community GitHub Issues
Developer Email: contact@counterscarp.io
Pro Priority Email (24hr response)
Team Dedicated Slack/Discord
Enterprise Customer Success Manager

Contact

Email: contact@counterscarp.io
Website: https://counterscarp.io

Last updated: April 2026 | Version 3.1.0

Scarpshield Wiki (Counterscarp Engine)

GitHub Repo | Web App | PyPI

Clone this wiki locally