Skip to content
dodobrandsPublic

About

Deterministic security scanner for AI-generated codebases

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

69 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AITriage logo

AITriage

Security scanners → SecureCoder AI triage → human decision → verified fixes

One security workflow for AI coding agents, Web, CI/CD, and the terminal.

Latest release Test status Docker scanner bundle MIT license

Install · AI IDE · Web · CI/CD · CLI · Reports


AITriage runs deterministic checks plus Semgrep, Trivy, Gitleaks, and Bandit. Its SecureCoder workflow then validates the findings, separates confirmed vulnerabilities from uncertain results and false positives, and prepares remediation instructions. Source code changes require a user decision.

1. Install once

AITriage is a system tool, not a dependency of the application being checked. Install it once on the computer; do not clone or copy AITriage into every project.

Set up through your AI IDE

Open Codex or Claude Code and paste this request:

Install the official released AITriage CLI on this computer and prepare its
complete scanner bundle. Official project: https://github.com/dodobrands/aitriage

Do not clone AITriage into my current repository and do not change its source.
If `aitriage` is missing, detect the host operating system and run exactly one
official installer:
- Native Windows PowerShell:
  `irm https://github.com/dodobrands/aitriage/releases/latest/download/install.ps1 | iex`
- macOS or Linux shell:
  `curl -fsSL https://github.com/dodobrands/aitriage/releases/latest/download/install.sh | sh`

Do not run the Unix installer on native Windows. Do not run the Windows
installer inside WSL. The installer verifies the release checksum and prepares
the complete scanner bundle. Do not download a binary from any other source.

Read the installer output. If the system executable directory needs an
administrator password but this AI IDE has no interactive terminal, the
installer safely uses `$HOME/.local/bin/aitriage`. On native Windows the
installer uses
`$env:LOCALAPPDATA\Programs\AITriage\bin\aitriage.exe` and updates User PATH.
Use the applicable exact executable path for the remaining commands when
`aitriage` is not yet on `PATH`; do not rerun the installer and do not edit
shell startup files without asking me.

Then run `aitriage version` and `aitriage setup --status --json` using the same
executable (absolute path if the current terminal has not picked up PATH yet).
If the status is not `ok`, show me its `message`, `action_url` (if present) and
`retry_command`, then stop. Never install Docker from another source.
If the status is `ok`, tell me the AITriage version, executable path, container
image, and status of every bundled scanner from that output. Do not connect a
project or run an audit yet.

The result is one host CLI plus one verified Docker image. The source repository is unnecessary for normal use.

Set up manually on macOS or Linux

Requirements: macOS or Linux on x86_64 or arm64, and a running Docker Desktop or Docker Engine.

curl -fsSL https://github.com/dodobrands/aitriage/releases/latest/download/install.sh | sh
aitriage setup --status

The installer downloads the matching official GitHub Release, verifies its SHA-256 checksum, installs the CLI into /usr/local/bin, and runs aitriage setup --full. To inspect the script before running it:

curl -fsSLO https://github.com/dodobrands/aitriage/releases/latest/download/install.sh
less install.sh
sh install.sh

In a non-interactive environment where the system executable directory needs administrator approval, the installer falls back to $HOME/.local/bin and prints the exact executable path. Add that directory to PATH for future shells if it is not already present.

Go 1.26.11 or newer with a C compiler (tree-sitter needs CGO) remains a developer fallback:

go install github.com/dodobrands/aitriage/cmd/aitriage@latest
aitriage setup --full

If Docker is missing or stopped, setup exits without scanning and prints one official installation link plus the same command to retry. It does not silently install Docker or individual scanners.

Windows (native, preview)

Preview. The Windows installer, binary, container paths and MCP configuration are covered by the required windows-latest CI job. The full Docker Desktop + Codex/Claude Code flow has not been run manually on Windows yet. Native Windows is x86_64 only; Windows ARM64 is not yet published.

Requirements: Windows 10/11 x86_64, PowerShell 5.1 or 7, and a running Docker Desktop in Linux-container mode. AITriage uses the same Linux scanner image as macOS/Linux and does not install Docker Desktop for you.

In PowerShell (no administrator required):

irm https://github.com/dodobrands/aitriage/releases/latest/download/install.ps1 | iex

Inspect-first (recommended):

irm https://github.com/dodobrands/aitriage/releases/latest/download/install.ps1 -OutFile install.ps1
# review install.ps1, then:
$installer = [ScriptBlock]::Create((Get-Content -Raw .\install.ps1))
& $installer

The installer verifies the release SHA-256, installs %LOCALAPPDATA%\Programs\AITriage\bin\aitriage.exe for the current user, adds it to your User PATH, and runs aitriage setup --full. It installs only the CLI and the official version-pinned scanner image — nothing else. Open a new terminal so the PATH update applies, then:

aitriage setup --status

Connect a project with the same commands as macOS/Linux:

aitriage install-codex .
aitriage install-claude-code .

For setup through an AI IDE, use the OS-aware prompt at the beginning of this section. It selects install.ps1 on native Windows without manual ZIP handling or PATH editing.

Uninstall (removes only the AITriage CLI and its User PATH entry; add -RemoveImage to also remove the downloaded scanner image):

$installer = [ScriptBlock]::Create((irm https://github.com/dodobrands/aitriage/releases/latest/download/install.ps1))
& $installer -Uninstall

WSL2 fallback

As an alternative to native Windows, use a WSL2 Linux distribution with Docker Desktop's WSL integration enabled and run the Linux installer inside WSL. Do not mix native Windows and WSL paths, binaries or MCP configs in one project:

curl -fsSL https://github.com/dodobrands/aitriage/releases/latest/download/install.sh | sh

What is installed

Part Where Purpose
aitriage CLI system executable path setup, project connectors, CLI, Web, MCP launcher
scanner image local Docker image cache AITriage, Semgrep, Trivy, Gitleaks, Bandit
scanner cache aitriage/scanners in the user cache directory reusable scanner databases; never stored in source
reports <project>/aitriage-reports/ results and local run state for that project

aitriage setup --full is safe to repeat after an upgrade. Remove only the downloaded AITriage image with aitriage setup --remove-runtime.

Choose how to use it

Interface Use it when AI access
AI IDE Codex, Claude Code, Cursor, Antigravity or VS Code should audit and help fix the open project subscription of the AI IDE you use
Web a person wants a local browser dashboard provider API key for AI triage
CI/CD pushes and pull requests need an automatic gate provider key in CI secrets
CLI terminal or scripts none for raw scan; provider key for full AI triage

2. AI IDE: Codex, Claude Code, Cursor, Antigravity, VS Code

This mode uses the model included in the AI IDE's own subscription. It does not need a separate LLM API key.

Two activation paths. Only Claude Code can approve the MCP server from the command line (claude mcp add), so it is live right after the connector runs when the claude CLI is on PATH (otherwise the connector writes .mcp.json and Claude Code asks you to approve the server). Cursor, Antigravity, VS Code and Codex have no scriptable approval: the connector writes the project-local config, then you must enable the aitriage server and approve its tools in that IDE's UI (Codex: trust the project) before opening a new session. Until you do, the server is not connected — and the agent must not pass off a raw aitriage scan as the audit.

Connect the open project through your AI IDE

First finish the one-time installation. Then open the root of the project to audit and paste:

Connect AITriage to the repository currently open in this AI IDE.

Run `aitriage setup --status --json` first. Stop if the complete scanner bundle
is not ready. Detect this client and run exactly one command from the open
repository root:
- Codex: `aitriage install-codex .`
- Claude Code: `aitriage install-claude-code .`
- Cursor: `aitriage install-cursor .`
- Antigravity: `aitriage install-antigravity .`
- VS Code (Copilot agent): `aitriage install-vscode .`
If you cannot tell which client you are, ask me instead of guessing.

Do not clone AITriage here. Preserve existing source, instructions, MCP servers,
and `.gitignore` entries. Do not audit or edit source during setup. Verify the
project-local MCP configuration and list the files changed. For Claude Code the
server is live immediately. For Codex, Cursor, Antigravity or VS Code, tell me
the exact UI step to enable the `aitriage` server and approve its tools — it is
NOT active until I do that. Then tell me to open a new task or session so the
client loads the server.

For Cursor, Antigravity, VS Code and Codex, enable and approve the aitriage server in the IDE now (the connector prints the exact step). Then open a new task/session in the same project. From then on, ordinary requests are enough:

Audit this project with AITriage. Do not fix anything yet.

AITriage—not the AI IDE—supplies the SecureCoder prompts, controls the workflow, and creates the final artifacts. The agent returns each model answer to AITriage until triage completes.

When you decide to fix findings, say which ones or explicitly approve all confirmed findings:

Fix the vulnerabilities AITriage confirmed. Leave uncertain findings and false
positives alone. Run the tests and verify the fixes with AITriage.

Connect manually

Run the one command for your IDE from the project root:

aitriage install-codex .         # Codex        → .codex/config.toml
aitriage install-claude-code .   # Claude Code  → claude mcp add (or .mcp.json)
aitriage install-cursor .        # Cursor       → .cursor/mcp.json
aitriage install-antigravity .   # Antigravity  → .agents/mcp_config.json
aitriage install-vscode .        # VS Code      → .vscode/mcp.json

Every connector uses the verified container runtime by default, preserves unrelated client settings, adds /aitriage-reports/ to .gitignore, writes a project-local config (never a global one), and confines tools to the opened root and its subdirectories. Claude Code is live immediately; for the others, enable and approve the aitriage server in the IDE UI as the command prints. Open a new task/session after connecting.

Windsurf is not supported as a first-class connector: it only reads a single global ~/.codeium/windsurf/mcp_config.json, which cannot keep one project's scan-root isolated from another. Point it at aitriage serve --runtime container --profile safe --scan-root <project> manually if you accept that trade-off (this is the command the connectors register; serve alone runs natively with the full, unconfined tool profile).

Update by running the same command again. Remove only the AITriage integration with --uninstall:

aitriage install-codex . --uninstall
aitriage install-claude-code . --uninstall
aitriage install-cursor . --uninstall
aitriage install-antigravity . --uninstall
aitriage install-vscode . --uninstall

3. Web UI

Web provides a local dashboard for findings, evidence, reports, and run history. It uses the same verified scanner image.

Start through your AI IDE

Start AITriage Web for the repository currently open in this AI IDE.
Run `aitriage setup --status --json` and stop if the scanner bundle is not ready.
Then run `aitriage web --project . --port 8080`, wait until it responds, and
give me the local URL and the command to stop it. Do not expose it to the
network, write credentials to files, or change source code.

Start manually

aitriage web --project . --port 8080

Open http://localhost:8080. Stop with Ctrl-C.

Web AI triage cannot use a Codex or Claude subscription. Set a supported provider key in the process environment when AI features are needed, for example:

export GEMINI_API_KEY="..."
aitriage web --project . --port 8080

The current Web server has no enforced login. It binds through the managed container to localhost; keep it local and do not expose it directly to the Internet.

4. CI/CD

CI uses the same AITriage pipeline and SecureCoder prompts, but its model is authenticated by a secret in the CI platform. A developer's local installation and subscription are not used.

Configure through your AI IDE

Add AITriage CI/CD to this repository using an official example from
https://github.com/dodobrands/aitriage/tree/main/examples/github-actions.
Preserve existing workflows. Never put a provider key in YAML or source code;
reference a GitHub Secret. Show me the workflow diff and required secret before
committing or pushing. Do not invent an organization-specific reusable workflow
URL: ask me if the approved URL is not already documented in this repository.

Configure manually

Choose the closest template in examples/github-actions/:

Copy the selected file to .github/workflows/ and set what its header comment lists: the repository variable AITRIAGE_ALLOWED_ACTOR_ID (every job is skipped while it is empty) and, for the AI templates, the provider key in GitHub Secrets. Trigger it once, then verify the uploaded reports, SARIF, and post-AI gate before making the check required.

The Action's fail-on, fail-score and health-profile inputs set the gate of command: scan. command: agent takes its gate from args, as the templates do, or from .aitriage.yaml. The agent exits 1 when the gate fails and 2 when the audit could not complete, for example because the provider rejected the key or rate-limited the run: treat 2 as a retry, not as a finding (see exit codes). To accept one assessed finding, such as a CVE, record it with aitriage ignore add and commit .aitriage-suppressions.json; the agent applies it in CI.

For organizations, the application workflow may call one centrally managed reusable workflow. Use the exact approved repository and secret names; AITriage documentation intentionally does not guess them.

5. CLI

Raw deterministic scan

aitriage scan .

This fast pre-scan uses built-in deterministic checks only. It requires neither Docker nor an AI key, but it is not a completed SecureCoder verdict.

Useful variants:

aitriage scan ./service
aitriage scan . --staged
aitriage scan . --diff origin/main
aitriage scan . --format sarif -o aitriage.sarif

Full AI audit

Provide a supported provider key and run:

export GEMINI_API_KEY="..."
aitriage agent . --no-chat

agent uses the full container scanner bundle by default and runs the same SecureCoder pipeline used by CI. Without extra output flags it writes a run bundle to aitriage-reports/ (see Reports). Provider variables include GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, and GROQ_API_KEY; --provider and --model override the auto-detected choice. It exits 1 when a configured gate fails and 2 when the audit could not complete (exit codes).

When no model is set (--model, AITRIAGE_LLM_MODEL or llm.model), AITriage uses the provider's default, and the run says which one when it starts (No model set; using gpt-4o, the default for openai):

Provider Default model
gemini gemini-3.5-flash-lite
anthropic claude-sonnet-5-5
openai gpt-4o (gpt-6-luna from AITriage 1.16)

OpenAI shuts down the gpt-4o snapshots on 2027-01-14, so AITriage 1.16 will default to gpt-6-luna; until then a run that relies on the OpenAI default warns about it on stderr and in the summary. Groq and Ollama serve models of their own: without llm.model AITriage sends them the OpenAI default, as earlier releases did, and warns that the server probably does not have it; set one. A default moves when its provider retires the model, and the verdicts move with it (the gate); to keep a model, set llm.model. Claude 5 models think before they answer: AITriage leaves room for that in max_tokens and reads only the answer. A reply cut off at max_tokens, or one with no text, is never read as an answer: classification asks again in smaller requests, and the report and fix spec fall back to their deterministic form. A request Claude declines (stop_reason: refusal) is no answer either: the log names the refusal category, and a declined classification request is split, without using up the retries, until the finding Claude declines is alone. The other findings get their verdicts; the declined one is not sent again and stays Needs Manual Review (unclassified) with a rationale that names the refusal, so the run exits 2. llm.disable_thinking (AITRIAGE_LLM_DISABLE_THINKING) applies to the openai, groq and ollama providers only, which send it to their OpenAI-compatible endpoint; Anthropic requests never carry it, and Claude 5 models think by default.

AITriage asks the model for temperature 0, so the same finding gets the same verdict on every run; provider defaults, often 1, draw a new answer each time. Set another value from 0 to 2, or default to send none, with --temperature, AITRIAGE_LLM_TEMPERATURE or llm.temperature in .aitriage.yaml, in that order of precedence. Models that take no temperature get none: OpenAI reasoning models (the o-series, GPT-5 and GPT-6), Gemini 3 and later, and Claude models released after Claude Opus 4.6, also under a gateway prefix or an Amazon Bedrock name (anthropic/claude-opus-4.7, us.anthropic.claude-sonnet-5-5-v1:0). R1-style reasoning models get none either (DeepSeek-R1 and its distills, deepseek-reasoner, QwQ): at temperature 0 they can repeat themselves until the request times out. When any other endpoint refuses the temperature, answering 400 or 422 with an error that names it as the refused parameter ("param": "temperature", or a message that calls it unsupported, not allowed or invalid), AITriage repeats that request without it and sends none for the rest of the run; an error about anything else keeps the temperature, also when it repeats the request's "temperature": 0. llm_usage in triage-findings.json records the provider, model and temperature the requests carried (provider default when no temperature, as in an AI IDE run, whose model AITriage does not configure), so verdicts that moved between runs can be traced to a change of model or temperature; the verdict cache keeps verdicts made at different temperatures apart.

To use a Codex or Claude subscription instead of an API key, use the AI IDE integration.

Reports

All project-owned output lives under one ignored directory:

aitriage-reports/
├── run-.../
│   ├── summary.md            # start here
│   ├── report.md             # full SecureCoder report
│   ├── fixspec.md            # remediation instructions
│   ├── triage-findings.json  # all AI verdicts
│   ├── aitriage.sarif        # standard scanner output
│   ├── manifest.json         # state, scanner coverage, integrity metadata
│   ├── scan.json             # AI IDE runs: deterministic input to triage
│   └── audit.log             # AI IDE runs: run events
├── baselines/                # container runtime: local baseline copies
├── suppressions/             # container runtime: local dismissal copies
├── cache/                    # verdict and artifact cache
├── history/                  # deterministic scan history
└── web/                      # local Web state

Connectors add /aitriage-reports/ to .gitignore. AITriage excludes this directory from every scanner and AI context so its own output cannot trigger another audit loop. List or remove AI IDE run bundles with aitriage runs list . and aitriage runs clean . (--dry-run previews; unfinished runs are kept unless you pass --force).

Paths in every report are relative to the project root. When several scanners report the same vulnerability class at the same file:line, the report shows one finding that lists every scanner as an origin; different classes on one line stay separate. Tools that read triage-findings.json should check finding.origins[], which lists every scanner that reported the defect; finding.source names only the one shown (for a hardcoded secret that is Gitleaks whenever Gitleaks reported it). The summary header groups dependency CVEs by package, while the score and the gate still count each CVE. A finding's ID (CS-<CLASS>-<6 hex>; the full stable_id is in triage-findings.json) is derived from its class, its file and the content of the flagged line, so edits elsewhere in the file keep both the ID and the cached verdict. Dismissed findings are left out of SARIF output, because GitHub code scanning does not honour the SARIF suppressions property; they stay in triage-findings.json and in the summary counts. Dismissing any one scanner's report of a defect dismisses the merged finding.

Scope, cost and the gate verdict

What is in scope

AITriage audits the application you ship, not everything on disk. By default it skips files git ignores and directories holding third-party or generated code (vendor, node_modules, dist, .next, __pycache__, venv). A build directory is scanned unless git ignores it: generated build output is ignored in practice, and a committed one, such as Go's build/package/Dockerfile, is your own. The same rules apply to every scanner: the built-in engine, the bundled Semgrep, Trivy, Gitleaks and Bandit, the NFR and deploy checks, and the git-history secret scan, so a vendored dependency is never reported as your vulnerability.

Setting Effect
AITRIAGE_RESPECT_GITIGNORE=false Audit ignored files too. Use when the question is "did a secret ever reach this working tree", not "is my application vulnerable"
AITRIAGE_SCAN_VENDORED=true Audit vendored and generated directories as if they were your own source
.aitriageignore Per-project excludes, same syntax as .gitignore, always honoured
ignore.paths in .aitriage.yaml Same syntax as .gitignore, relative to the project root, always honoured by every scanner. As in git, a pattern with a slash before its last character (app/legacy/) is anchored at the root; use **/app/legacy/ for any depth

The built-in engine used to match ignore.paths as substrings, so vendor also hid src/vendors/ and .git hid .github/. Such directories are scanned again; for one release AITriage warns about each pattern that no longer hides a path and names the entry to add if it should stay out of scope.

The two variables change what the bundled scanners and the git-history scan cover; the built-in engine always skips ignored files and those directories. They are read by the process that runs the scanners: set them in the GitHub Action's job environment or in your shell. The local container launcher used by agent and web forwards them along with provider keys, the AITRIAGE_LLM_* settings, AITRIAGE_BATCH_SIZE, AITRIAGE_CLASSIFY_RETRIES, AITRIAGE_CONCURRENCY, AITRIAGE_POC_BUDGET and AITRIAGE_GATING.

Network findings describe the machine AITriage runs on rather than the repository, so probing is opt-in: aitriage agent --probe-compose probes the services declared by the project's Compose file, --probe <host> a host of your choice, and a Web scan probes only when it is asked to. A name that does not resolve, as Compose service names in CI do not, is not a finding. Network findings are reported, but never sent to the LLM and never counted in the score or the gate.

Trivy reports dependency vulnerabilities and IaC misconfigurations (Terraform, Kubernetes manifests, Dockerfiles and similar files). It applies the repository's own ignore file to both scans: .trivyignore, or .trivyignore.yaml / .trivyignore.yml. Trivy reads one ignore file per run, so when both forms exist the YAML file is used and a warning names the one left out. The file is read from the repository root wherever AITriage runs, including the container. scanners.trivy.ignore_unfixed and scanners.trivy.severity in .aitriage.yaml narrow what Trivy reports; see the configuration example.

Hardcoded secrets

A hardcoded secret is never dismissed automatically: a person decides. Two kinds of reports are kept out of that queue or ranked lower, because they are not live secrets:

  • In a Compose file, a password or secret whose value is a default or easily guessed one is reported as compose_default_credential (MEDIUM) instead of compose_hardcoded_secret (CRITICAL). That is a default account name or a documented default of a common image (postgres, minioadmin), a sequence (12345678), one of those with digits or a password word appended (admin123), and, unless the value is random enough to have been generated (the built-in secret detector's own threshold), the name of a service, image, user or database in the same file (appuser_pass next to APP_USER: appuser) or a placeholder written as a word of its own (changeme, your-password-here). A value is never ranked lower for being short, or for containing such a word inside a longer one. It is still a hardcoded secret for a person to review. Values Compose substitutes (${DB_PASSWORD}, $DB_PASSWORD), *_FILE paths to secret files, and a yes/no, true/false or 1/0 under the MySQL and MariaDB images' password switches (MYSQL_RANDOM_ROOT_PASSWORD, MYSQL_ALLOW_EMPTY_PASSWORD, MARIADB_RANDOM_ROOT_PASSWORD, MARIADB_ALLOW_EMPTY_ROOT_PASSWORD) are not reported. ignore.rules entries, inline comments, baseline entries and dismissals written for compose_hardcoded_secret still cover default credentials.
  • Bandit's hardcoded-password reports (B105, B106, B107) are dropped when the string they quote cannot be a credential: it is empty; it is a message about a credential, that is two or more words that name one (password, token, secret, key, username, login…) or hold a format placeholder (%s, {}), unless one of its words could itself be a credential; or it is the name of a token issued at run time (csrf_token, X-XSRF-TOKEN) that the quoted code uses as a cookie, header or mapping key. Every other value, weak ones and passphrases included, is still reported.

Silencing rules and findings

Mechanism What it silences
ignore.rules in .aitriage.yaml Every finding of a rule, from any source: built-in rules and heuristics, Semgrep, Trivy, Gitleaks, Bandit, NFR, deploy and network checks. A bare ID matches any source; gitleaks:generic-api-key, trivy:CVE-2024-1234 or semgrep:<check-id> match one scanner, and core:, nfr:, deploy: or network: one of AITriage's own checks
An inline comment The rules it names, at one place in the source: built-in, external-scanner and deploy findings
aitriage ignore add Findings a person reviewed and dismissed as a false positive, accepted risk or won't-fix, recorded in .aitriage-suppressions.json

A Trivy Kubernetes (KSV) or Dockerfile (DS) check matches in each spelling Trivy releases have used, in ignore.rules and in inline comments: KSV012, KSV-0012 and AVD-KSV-0012 (with or without trivy:) name one check, as do DS002, DS-0002 and AVD-DS-0002. Every other ID compares as written: other Trivy checks (tfsec's AWS001 is not AWS-0001), short forms Trivy never reported (KSV12), advisories (CVE-…, GHSA-…) and other scanners' IDs.

Inline directives name the rules they silence. IDs compare whole, text after the list (such as a reason) is never read as an ID, and all silences every rule only as an ID of its own:

token = "fixture"  # aitriage-ignore: B105, gitleaks:generic-api-key (test data)
# aitriage-ignore-next-line: PY-SUBPROCESS
# aitriage-ignore-file: ENTR-12    (first 10 lines; without IDs it covers every rule)

aitriage-ignore (or aitriage:ignore) covers its own line and the next one; -next-line covers only the next one. A directive counts only when it opens a comment; a mention in prose, Markdown text or a string literal (including multi-line strings such as Python docstrings, JS template literals and Go raw strings) is ignored. Rule IDs may be separated by commas or spaces; the list ends at the first word that does not look like a rule ID, or at (, so aitriage-ignore: B105 allowed in tests silences only B105.

Commit .aitriage-suppressions.json: aitriage agent (in CI too), AI IDE runs and the Web UI apply it, and a dismissed finding is not sent to the LLM. This is how to accept a specific CVE in CI:

aitriage ignore add CVE-2024-1234 --source trivy --reason accepted-risk \
  --note "the vulnerable parser never receives user input"

A decision matches findings of its --source and rule. Without --file it covers them anywhere in the project, with --file every one in that file, and --evidence makes it exact: only the finding whose matched text it quotes (with no --file, only a finding that has no file). The Web API (POST /api/suppressions) and the AI IDE tool refuse a decision without a file unless rule_wide: true is passed, and every response states which findings the decision covers, so one call cannot silently dismiss a rule across the whole project. Dismissing any one scanner's report of a merged finding dismisses that defect only; it never covers a different rule's project-level check or another container in the same manifest. Dismissals made in the Web UI or an AI IDE under the container runtime are kept in a local copy first; see the baseline notes below.

Why the gate can fail with nothing confirmed

A scanner finding is a hypothesis until someone confirms it. AITriage reports three states: confirmed, needs review and suppressed (false positive, accepted risk, resolved). The default policy is fail-closed: unreviewed findings block, because unreviewed is unresolved, not proven safe. This matches how Sonar quality gates and GitHub code scanning behave — an alert must be triaged or dismissed before it stops blocking.

That default has a known failure mode on an existing codebase: the gate judges years of accumulated debt, and the team learns to override it. Choose deliberately:

Setting Meaning
fail_on: critical (default) Active CRITICAL/HIGH findings block
fail_on: any Any active finding blocks, reviewed or not. Findings reported under iac_findings: report (the default) and quality_findings: report (when set) are not active: they are listed but never block
fail_on: confirmed Only findings AI triage confirmed block; unreviewed are reported, not blocking. confirmed_min_severity (--confirmed-min-severity) limits this to confirmed findings at or above MEDIUM, HIGH or CRITICAL; the default LOW keeps every confirmed finding blocking
fail_on: never The gate never blocks; the score is informational
iac_findings: report (default) / block IaC misconfigurations from Trivy (Dockerfile, Kubernetes, Terraform). report triages and shows them in the summary, the report and triage-findings.json but keeps them out of the score and the gate, and the summary says how many; block (--iac-findings block) gates them like any other finding. A finding another check also reported (for example DOCKER-NO-USER and Trivy's DS-0002) gates either way, and so does one a block_sources or block_classes entry names (block_sources: [trivy], block_classes: [KSV-0012]). report stays the default throughout v1; a default change follows the compatibility policy
quality_findings: block (default) / report Code-quality findings with no security impact, at LOW or INFO: rules of subcategory quality (built in: ENTR-04, ENTR-07, ENTR-12, ENTR-AI-RESIDUE, ENTR-ZOMBIE-CODE, FAST-SYNC-ASYNC) and the NFR check for a missing .env.example. A swallowed exception (FAST-LAZY-EXC, Bandit's B110 and B112) is not one: except Exception: pass around a token check turns a failed check into a pass. block scores them and gates on them like any other finding, as before this setting existed. report (--quality-findings report, on aitriage agent and aitriage scan) triages and shows them like IaC findings under iac_findings: report, but keeps them out of the score and the gate. A finding a security check also reported, a MEDIUM or more severe one whatever its rule's subcategory, and one a block_sources or block_classes entry names gate either way. block stays the default throughout v1
aitriage baseline create . Accept today's findings as the starting line; aitriage scan . --baseline then reports and gates only new findings

Set fail_on under health_check: in .aitriage.yaml or with --fail-on. aitriage scan, including the Action's default scan command, uses critical; a raw scan confirms nothing, so fail_on: confirmed alone never blocks it. aitriage agent applies a gate only when one is configured in .aitriage.yaml or passed with --fail-on, --fail-score or --health-profile. iac_findings and quality_findings mean the same wherever a scan is scored: aitriage scan, the scans the Web UI, the TUI and MCP tools run, aitriage baseline, and AI triage. The aggregate scores on the Web UI dashboards are an exception: they are computed from stored findings without these settings and count every open finding. The breakdown of the health check counts the findings the settings keep out of the score in report_only_findings, the total of both, split by setting in report_only_by_kind (iac, quality). A block_classes entry that names a Trivy Kubernetes or Dockerfile check matches it in each spelling Trivy has used (KSV012, KSV-0012, AVD-KSV-0012), as in ignore.rules; every other ID compares as written.

The score and the gate answer different questions. The score counts every active finding, reviewed or not, code-quality findings included unless quality_findings: report is set, so a project with many unreviewed findings can score low while a gate that blocks only confirmed findings passes. When that happens and unreviewed findings cause most of the penalty, the summary says so in one line, for example: Score 68/100: 3 finding(s) await review and count in full (all 32 penalty points), but fail_on: confirmed blocks only confirmed findings at or above MEDIUM. Before triage, aitriage agent prints the Pre-triage health check (all scanners, nothing reviewed yet): every scanner, under the run's policy, with every finding unreviewed.

Under fail_on: confirmed the gate is only as stable as the model's verdicts, and verdicts differ noticeably between models on the same code. Pin one model (llm.model or --model) and re-check a project you know before switching to another. fp_critical_requires_high_confidence: true (--fp-critical-requires-high-confidence) keeps a CRITICAL finding for manual review unless the model calls it a false positive with high confidence. A false positive also needs evidence AITriage can check. A code mitigation must be code (not a comment, a string, a configuration file or the flagged line itself), in the same file and the same function at most 30 lines above the flagged line, name a variable or function the flagged statement uses, and be a guard of it (an if, elif or assert that checks it and exits early or encloses the flagged statement) or a re-assignment of it through a call (cmd = shlex.quote(cmd)). AITriage checks this on the syntax tree for Python, Go, JavaScript and TypeScript; in other languages a HIGH finding dismissed this way stays Needs Manual Review. A CRITICAL finding is never dismissed by a code mitigation, and a hardcoded secret by no evidence at all, not even in a test file: they stay Needs Manual Review until a person decides.

A baseline is a property of the project, not of the tool that created it. The shared record is .aitriage-baseline.json at the repository root, used by the CLI (aitriage baseline), the Web UI (SecureCoder → Baseline) and an AI IDE (aitriage_baseline); a Web scan can hide baselined findings. Under the MCP safe profile only inspection is offered, because accepting findings writes to the project.

The container runtime mounts the project read-only, so there the Web UI and the MCP tools write baselines and dismissals to a local copy under aitriage-reports/baselines/… and aitriage-reports/suppressions/…. Scans in the container read the project file and that copy together, and the copy wins for the same entry. The copy is local and git-ignored, so CI and other checkouts never see it: move its contents into .aitriage-baseline.json or .aitriage-suppressions.json at the project root and commit that file. The host CLI (aitriage baseline create ., aitriage ignore add) writes those files directly.

A baseline records findings from every scanner that ran when it was created: the built-in engine, Semgrep, Trivy, Gitleaks, Bandit, and the NFR and deploy checks. Network findings are never baselined. aitriage baseline create runs on the host, so it records Semgrep, Trivy, Gitleaks and Bandit findings only where those tools are installed locally.

For a legacy codebase adopting AITriage, aitriage baseline create . is usually the right first move: it keeps every finding visible in reports while the gate judges only new work.

Exit codes

Code Meaning
0 The gate passed, or no gate applies
1 The security gate failed. Usage errors and setup problems caught before the run starts (Docker not running) also exit 1
2 aitriage agent could not complete the audit: no usable LLM provider, a provider failure (rejected key, rate limit, timeout) or replies that classify nothing (empty, malformed, declined, or only rejected verdicts), a required scanner that did not run in the container, or a report that could not be written. Re-run once the cause is fixed

A provider failure no longer discards the run. When triage is cut short, AITriage still writes every report: triage-findings.json records triage_status: failed and the reason, the summary, report and fix spec open with a banner, and findings left without a verdict are marked triage-failed. The gate then fails with triage_incomplete under every fail_on except never, so an outage cannot turn the check green. A failure in an optional stage (PoC traces, the report or fix-spec narrative) falls back to a deterministic rendering, is noted in the summary, and leaves the exit code to the gate.

Controlling AI cost

Deterministic scanning, the security score, the gate verdict and every report format cost nothing — they need no LLM at all. Only triage, PoC reasoning and the written narrative use a provider.

Lever Effect
Verdict cache A re-run of the same findings reuses stored verdicts, and the report prints the reuse percentage. On for local agent, Web and AI IDE runs (aitriage-reports/cache/); in the GitHub Action, set the verdict-cache-dir input
AITRIAGE_GATING=on Send only CRITICAL/HIGH findings to the LLM. The rest get a deterministic Needs Manual Review — never an automatic dismissal. Set it where the scope variables above go
AITRIAGE_BATCH_SIZE Findings per request (default 40; llm.batch_size in .aitriage.yaml). Larger batches cost fewer round trips, but weaker models drop items from long requests; a reply that cannot be parsed or misses more than a quarter of its findings is retried in halves
AITRIAGE_CLASSIFY_RETRIES Extra passes for findings the model left without a verdict (default 2). What is still left is Needs Manual Review (unclassified), counted separately in the summary together with the retries and batch size used
Provider choice Cost depends on the model, and so do the verdicts (see the gate): pick one model deliberately and keep it pinned

If no provider key is set, Web still scans, scores, applies the policy and generates every report format. The AI panels report that they are offline instead of failing the run.

Safety contract

  • A full run fails closed if Docker or any required scanner cannot run.
  • Every report records whether each scanner completed or was deterministically not applicable.
  • The source tree is mounted read-only inside the scanner container; only aitriage-reports/ is writable there.
  • MCP tools are confined to the opened repository root and real subdirectories; traversal and symlink escapes are rejected.
  • AITriage supplies the canonical SecureCoder prompts. The host agent must not replace them with an ad-hoc review.
  • No source change is authorized by a scan. The user chooses whether and what to fix.

Troubleshooting

Problem Action
Docker is absent or stopped Follow the official URL printed by aitriage setup --full, start Docker, then repeat the same command
Runtime is incomplete after an upgrade Run aitriage setup --repair, then aitriage setup --status
An AI IDE cannot see AITriage Re-run the matching connector from the repository root and open a new task/session
Claude shows MCP approval pending Open Claude Code in the project and approve the local aitriage server
Cursor / Antigravity / VS Code shows nothing, or the agent improvises The connector only writes the config; enable the aitriage server and approve its tools in the IDE UI, then open a new session. These clients have no scriptable approval
A real subdirectory is rejected Reconnect from the intended repository root; paths outside it and symlink escapes are deliberately blocked
The agent ran only aitriage scan Ask it to use the AITriage MCP workflow; raw scan is not AI triage
Web AI is unavailable Export a supported provider API key before starting Web
Full audit failed Keep the error visible and repair the runtime; do not present a reduced scan as the final verdict
aitriage agent exited 2 The audit did not complete. If triage-findings.json says triage_status: failed, its reason names the provider error (key, rate limit, timeout): re-run when the provider is available. If manifest.json shows a scanner as missing or failed, repair the runtime
Many findings are Needs Manual Review (unclassified) The model returned no verdict for them. Re-run, raise AITRIAGE_CLASSIFY_RETRIES or lower AITRIAGE_BATCH_SIZE
The summary says the model declined to classify findings Claude declined them (stop_reason: refusal), each sent on its own, and the same model is likely to decline them on every run. Review them by hand: fix a real issue, record a false positive or an accepted risk with aitriage ignore add, which keeps the finding away from the model, or triage with another model
Semgrep findings in a large file come and go between runs Semgrep stops analysing a file after repeated rule timeouts, and timeouts depend on machine load. The summary names the files Semgrep analysed only partly, and manifest.json lists them under scanners[].partial_files with the reason (timeout, parse_error, error). If such a file is generated, exclude it with ignore.paths
A warning says an ignore.paths pattern no longer excludes a path Patterns use .gitignore syntax now. Add the suggested entry if the path should stay out of scope
Every Kubernetes manifest without metadata.namespace is reported as running in the default namespace (Trivy KSV-0110) Trivy reads a missing namespace as default; it cannot see a namespace set at deploy time. If your deploy sets one (kubectl apply -n, Helm, Kustomize), add trivy:KSV-0110 to ignore.rules (any spelling, such as KSV110, matches). Under the default iac_findings: report these findings do not gate unless block_sources or block_classes names them
Images from your own registry are reported as untrusted (Trivy KSV-0125) Trivy trusts only a built-in list of registries. If your cluster policy already restricts registries, add trivy:KSV-0125 to ignore.rules or list it in .trivyignore
A dismissed finding still fails CI Commit .aitriage-suppressions.json. A dismissal made in the Web UI or an AI IDE under the container runtime sits in aitriage-reports/suppressions/… until you move it into that file. aitriage agent applies the file; the raw aitriage scan does not

Project documentation

License

MIT. See LICENSE.

About

Deterministic security scanner for AI-generated codebases

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages