SIREEN SIREEN
Documentation

AI-Assisted Mode

SIREEN works fully offline with heuristic analysis. Enabling AI-assisted mode adds optional LLM-powered hypothesis exploration — but every AI suggestion still requires Forge verification before a finding is confirmed.

What AI-Assisted Mode Does

  • Scans contract source — The LLM reads the contract to understand its architecture, trust boundaries, and state transitions.
  • Suggests hypotheses — Proposes attack angles beyond the built-in heuristic patterns.
  • Still requires verification — Every AI-generated hypothesis goes through the same Forge verification pipeline as heuristic ones. No AI output is ever auto-confirmed.
Important

AI-assisted mode is wired but unevaluated for hypothesis quality. The pipeline has been tested for connectivity, but we have not systematically measured whether AI-generated hypotheses produce better, worse, or different findings than heuristic-only mode. Use it experimentally and report your experience.

Setup — Connect Any LLM API Key

SIREEN connects to LLMs through OpenRouter, which supports any API key you already have — free or paid. You are not locked into a single provider.

Step 1 — Get your API key

You have two options:

Option A — Use an existing key (OpenAI, Anthropic, Google, DeepSeek, etc.)

OpenRouter accepts keys from major providers. Sign in at openrouter.ai, link your existing provider key, and OpenRouter will route requests for you.

Option B — Create a free OpenRouter key
  1. Go to openrouter.ai.
  2. Sign up (email or OAuth).
  3. Navigate to Keys and create a new API key.
  4. Copy the key (starts with sk-or-v1-).

No credit card is required. Free-tier models are used by default.

Step 2 — Link your key to SIREEN

cd goalaif/gaolaif/backend
cp .env.example .env.local

Edit .env.local and paste your key:

OPENROUTER_API_KEY=sk-or-v1-YOUR-KEY-HERE

Replace YOUR-KEY-HERE with your actual key. SIREEN reads this variable at runtime.

Step 3 — Verify the connection

sireen audit ./Contract.sol --json | grep reasoning_mode

Expected output: "reasoning_mode": "LLM_ASSISTED"

If you see HEURISTIC, the key was not read. Check that .env.local is in the correct directory and the variable name is exactly OPENROUTER_API_KEY.

Which Models Does SIREEN Use?

By default, SIREEN routes to free-tier models through OpenRouter:

  • Scanner: nvidia/nemotron-3-ultra-550b-a12b:free
  • Attacker: nvidia/nemotron-3-super-120b-a12b:free
  • Verifier: nvidia/nemotron-3.5-content-safety:free
  • Judge: nvidia/nemotron-3-super-120b-a12b:free
  • Documenter: cohere/north-mini-code:free

If you link a paid provider key (OpenAI, Anthropic, etc.), OpenRouter will use your credited balance to route requests. You can also configure specific models in your SIREEN settings.

Privacy note

Contract source is sent to OpenRouter's API (and then to the underlying LLM provider). Do not enable AI mode on contracts you are not authorized to share externally. For sensitive code, use heuristic-only mode.

Troubleshooting

ProblemFix
reasoning_mode: HEURISTICKey not read. Check .env.local exists in goalaif/gaolaif/backend/ and contains the correct key.
HTTP 401 errorsInvalid or expired key. Regenerate at openrouter.ai.
HTTP 429 errorsRate limit hit. Wait a moment, or switch to a paid provider key for higher limits.
Slow responsesFree-tier models have rate limits. Add delays between requests or link a paid provider key.