1. Install
You need Python 3.11+ and pip. Foundry is optional but strongly recommended.
The SIREEN source repository is not publicly readable today, so git clone below will fail until access is granted. Request access from the project owner at github.com/0766243478. See the download page for details. Checked 2026-10-15.
git clone https://github.com/0766243478/goalaif.git cd goalaif/gaolaif/backend python -m pip install -r requirements.txt python -m pip install -e .
Verify the installation:
sireen --help
Expected output: usage information for the sireen command.
If sireen is not found, your Python Scripts directory may not be on PATH. Use python -m sireen_cli as a fallback.
2. Configure your API key (optional)
SIREEN works fully offline. An API key enables AI-assisted hypothesis generation. You can use any LLM provider key — OpenRouter accepts keys from OpenAI, Anthropic, Google, DeepSeek, and others.
- Go to openrouter.ai and sign up (free).
- Either create a new OpenRouter key (
sk-or-v1-...) or link an existing provider key. - In the backend directory, run:
cp .env.example .env.local - Edit
.env.localand add your key:OPENROUTER_API_KEY=sk-or-v1-YOUR-KEY-HERE
.env.local is gitignored. Never commit it. Never share it. Each researcher must use their own key. If leaked, revoke it immediately.
3. Run your first analysis
We will use the built-in test fixture VulnerableVault.sol, a contract with a known reentrancy bug.
sireen audit ../../test_projects/critical_reentrancy/src/VulnerableVault.sol --report
This command:
- Reads the contract source
- Discovers functions, state variables, and external calls
- Generates a reentrancy hypothesis
- Produces a Foundry PoC test file
- Attempts to compile and run it with Forge (if available)
- Writes a Markdown report
Without Forge, the audit completes in a few seconds. With Forge, it may take 10–30 seconds depending on compilation time.
Use --json for machine-readable output, or --project to audit an entire Foundry project directory.
4. Read the output
After the audit finishes, you will see a summary like this:
SIREEN Forge-backed adversarial security workbench FILE ../../test_projects/critical_reentrancy/src/VulnerableVault.sol DISCOVERY OK HYPOTHESIS 1 generated ATTACK PATH 1 inspectable POC GENERATED FORGE Version: unavailable Compile: FAILED Test: NOT_RUN Executed: 0 FINDINGS REENTRANCY [NEEDS REVIEW] Reentrancy on withdrawEntireBalance Evidence: evd-ce5159fb8f56 TERMINAL STATE DEGRADED
What each field means
| Field | Meaning |
|---|---|
terminal_state | The overall verdict: CONFIRMED, CLEAN_WITH_COVERAGE, DEGRADED, UNVERIFIED, or FAILED |
findings[].confirmed | true only if Forge executed the PoC and it passed |
findings[].needs_review | true when a PoC exists but was not executed (Forge missing) or the test failed |
reasoning_mode | HEURISTIC (offline) or LLM_ASSISTED (AI involved) |
execution_status | llm_executed, llm_unavailable, heuristic_only, or llm_error |
evidence[].poc_source | The complete generated Foundry test file |
Terminal states explained
| State | What it means | Your action |
|---|---|---|
CONFIRMED | Forge verified at least one finding. Evidence is complete. | Review the evidence pack and consider remediation. |
CLEAN_WITH_COVERAGE | No findings. Every hypothesis received a real Forge attempt. | Continue with manual review for out-of-scope vectors. |
DEGRADED | Findings exist but could not be fully verified. | Manually triage each needs_review finding. |
UNVERIFIED | Coverage was insufficient to classify. | Check if the contract has supported patterns (external calls, state variables). |
FAILED | Pipeline crashed or every PoC failed compilation. | Check Python/Forge versions and file a bug report. |
5. Review findings
If a finding is CONFIRMED
You have machine-verified evidence. The PoC compiled, ran, and its security assertions passed. Treat this as high-confidence evidence of a real vulnerability.
- Open the evidence pack via
sireen show <audit-id>. - Copy the
poc_sourceinto a file namedPoC.t.sol. - Run it yourself:
forge test --match-path '*PoC*' - If it passes, the vulnerability is independently reproducible.
If a finding is needs_review
This is the most common outcome when Forge is not installed. The heuristic detected a suspicious pattern and generated a PoC, but the PoC was not executed.
- Read the
poc_sourcein the evidence pack. - Judge whether the attack path is realistic.
- If you have Forge, copy the PoC into a test file and run it.
- If the test passes, the vulnerability is real.
- If the test fails or the PoC is nonsensical, it is likely a false positive.
Common false positives
- Accounting inconsistency: Any function that updates multiple state variables is flagged. Legitimate accounting code often triggers this.
- Reentrancy on guarded functions: The heuristic may flag an external call even when a
nonReentrantmodifier is present. - Access control on view functions: A function that reads privileged state but does not mutate it may be incorrectly flagged.
6. Report bugs and false positives
Your feedback directly improves the engine. Please report:
- False positive: A safe contract flagged as vulnerable
- False negative: An obviously vulnerable contract returns
CLEAN_WITH_COVERAGE - Crash:
FAILEDterminal state with an error - CLI/extension mismatch: Same file produces different results
- AI quality issue: LLM output is nonsense or irrelevant
Contact the project owner through their GitHub profile and include:
- The exact command you ran
- The contract source (or a minimal reproduction)
- The full output (use
--json) - Your environment: OS, Python version, Forge version
- Whether you had an OpenRouter key configured
# Audit one file sireen audit ./Contract.sol sireen audit ./Contract.sol --json sireen audit ./Contract.sol --report # Audit a project sireen audit ./my-foundry-project --project # Inspect results sireen audits sireen show <audit-id> sireen report <audit-id> --output report.md # Start backend server (for VS Code extension) python -m uvicorn main:app --host 127.0.0.1 --port 7432