Security Scanner

A comprehensive AI-powered security scanner built in TypeScript. Performs 16-phase static analysis, dynamic testing (DAST), container & IaC scanning, supply chain auditing, prompt-injection / AI-app security, STRIDE threat modeling, agent-powered line-by-line audits, and AI-assisted remediation. Ships with an LSP server for real-time editor diagnostics, a fingerprint-keyed suppressions DB, an incremental scan cache, and SARIF 2.1.0 output for GitHub Code Scanning.

Quick Start

npm install
npx tsx src/cli/index.ts scan              # basic 9-phase scan
npx tsx src/cli/index.ts scan --advanced   # full 16-phase scan

Scan Commands

# Basic scanning
npx tsx src/cli/index.ts scan                        # scan current directory
npx tsx src/cli/index.ts scan /path/to/project       # scan specific directory
npx tsx src/cli/index.ts scan --severity high        # only show high+ findings

# Full 16-phase scan (taint, crypto, race, supply chain, code quality, ...)
npx tsx src/cli/index.ts scan --advanced

# Deep code quality (null safety, logic bugs, cross-platform issues)
npx tsx src/cli/index.ts scan --advanced             # includes --quality phase

# Dependency analysis
npx tsx src/cli/index.ts scan --versions             # current vs latest
npx tsx src/cli/index.ts scan --cve                  # live CVE check (OSV.dev)
npx tsx src/cli/index.ts scan --license              # license compliance
npx tsx src/cli/index.ts scan --dep-behavior         # runtime behavior analysis
npx tsx src/cli/index.ts scan --reachability         # call-graph reachability

# Infrastructure / IaC / Containers (always on, also via --iac)
npx tsx src/cli/index.ts scan --iac                  # Terraform/CFN/Ansible

# Dynamic testing against a live server
npx tsx src/cli/index.ts scan --dast http://localhost:3000

# SBOM and secrets in git history
npx tsx src/cli/index.ts scan --sbom cyclonedx
npx tsx src/cli/index.ts scan --sbom spdx
npx tsx src/cli/index.ts scan --git-history

# Auto-fix
npx tsx src/cli/index.ts scan --fix
npx tsx src/cli/index.ts scan --fix-dry-run          # preview fixes only

# AI features (requires provider + API key)
npx tsx src/cli/index.ts scan --ai --ai-model gemini:gemini-2.5-flash
npx tsx src/cli/index.ts scan --ai-fix --ai-model gemini:gemini-2.5-flash
npx tsx src/cli/index.ts scan --ai-triage            # AI exploitability ranking
npx tsx src/cli/index.ts scan --ai-code              # AI-generated code smells
npx tsx src/cli/index.ts scan --deep                 # multi-agent deep audit

# Agent-powered line-by-line audit (flagship: 10 specialist agents)
npx tsx src/cli/index.ts scan --agent-audit --ai-model gemini:gemini-2.5-flash
npx tsx src/cli/index.ts scan --agent-audit --agents injection,auth,crypto

# PR review mode (scan only changed files)
npx tsx src/cli/index.ts scan --pr 42 --base-branch main

# Monorepo
npx tsx src/cli/index.ts scan --monorepo
npx tsx src/cli/index.ts scan --workspace my-app

# Policy / compliance frameworks
npx tsx src/cli/index.ts scan --policy SOC2
npx tsx src/cli/index.ts scan --policy HIPAA
npx tsx src/cli/index.ts scan --policy PCI-DSS

# Custom YAML rules (Semgrep-style)
npx tsx src/cli/index.ts scan --rules .agentsec/rules

# Live secret verification — probe issuer APIs to confirm a key is real
npx tsx src/cli/index.ts scan --verify-secrets

# STRIDE threat model — generate THREAT_MODEL.md from the codebase
npx tsx src/cli/index.ts scan --threat-model
npx tsx src/cli/index.ts scan --threat-model docs/threat.md

# Suppressed findings — include them in the report (marked [SUPPRESSED])
npx tsx src/cli/index.ts scan --show-suppressed

# Incremental scan cache — on by default; control with --no-cache / --clear-cache
npx tsx src/cli/index.ts scan --no-cache
npx tsx src/cli/index.ts scan --clear-cache

# Combine flags
npx tsx src/cli/index.ts scan --advanced --versions --cve --license --ai-triage

# Profile presets — bundle common flag combinations into one switch
npx tsx src/cli/index.ts scan --profile minimal    # secrets+deps+OWASP, high+ only
npx tsx src/cli/index.ts scan --profile balanced   # core 9-phase + versions/CVE
npx tsx src/cli/index.ts scan --profile strict     # 16 phases + license + reachability + verify-secrets
npx tsx src/cli/index.ts scan --profile ci         # 16 phases + SARIF + fail-on high
npx tsx src/cli/index.ts profiles list             # list all available profiles
npx tsx src/cli/index.ts profiles show strict      # inspect one profile's options

# Scan diff — compare two git refs and report only changed findings
npx tsx src/cli/index.ts scan-diff main HEAD                               # what did this branch add?
npx tsx src/cli/index.ts scan-diff v1.2.0 v1.3.0 --advanced                # release-over-release delta
npx tsx src/cli/index.ts scan-diff main HEAD --fail-on-new high            # CI gate: block only on NEW high+ findings
npx tsx src/cli/index.ts scan-diff main HEAD --json                        # machine-readable output

Custom profiles

Define project-specific presets as YAML under .agentsec/profiles/<name>.yml:

description: Web team defaults — strict on auth, lax on deps
options:
  severity: medium
  advanced: true
  category: secret,vulnerability,auth

Then apply with scan --profile <name>. Any flag the user passes explicitly on the CLI still wins — profile values only fill in defaults.

Output Formats

npx tsx src/cli/index.ts scan -f json -o report.json
npx tsx src/cli/index.ts scan -f html -o report.html
npx tsx src/cli/index.ts scan -f markdown -o report.md
npx tsx src/cli/index.ts scan -f sarif -o results.sarif    # SARIF 2.1.0 — uploadable to GitHub Code Scanning
npx tsx src/cli/index.ts scan -f junit -o results.xml

CI/CD Mode

# Structured output with exit codes for pipelines
npx tsx src/cli/index.ts scan --ci --fail-on high --advanced

# Baseline diff (only show new findings)
npx tsx src/cli/index.ts scan --save-baseline         # save current state
npx tsx src/cli/index.ts scan --baseline               # compare against saved
npx tsx src/cli/index.ts scan --ci --baseline --update-baseline

GitHub Action

A composite action ships at .github/actions/agentsec/. Drop it into any workflow:

permissions:
  contents: read
  security-events: write
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/agentsec
        with:
          profile: ci
          fail-on: high
          # diff-base: ${{ github.event.pull_request.base.sha }}   # uncomment to gate only on NEW findings

The action installs AgentSec, runs a ci-profile scan (or a scan-diff if diff-base is set), uploads the SARIF report to GitHub Code Scanning, and fails the job when the gate isn't satisfied. See .github/actions/agentsec/README.md for the full input reference.

Watch Mode

# Re-scan automatically when files change
npx tsx src/cli/index.ts scan --watch

Dashboard

# Launch web UI (http://localhost:3000)
npx tsx src/cli/index.ts dashboard
npx tsx src/cli/index.ts dashboard --port 8080
npx tsx src/cli/index.ts dashboard --scan .            # scan first, then open

Interactive Chat

npx tsx src/cli/index.ts chat
npx tsx src/cli/index.ts chat -m gemini:gemini-2.5-flash

# In chat, use slash commands:
#   /scan [dir]       — run a security scan
#   /explain <vuln>   — explain a vulnerability or CWE
#   /tools            — list available tools
#   /cost             — show session cost
#   /help             — all commands

Scan Phases

| # | Phase | Flag | What it checks | |---|-------|------|----------------| | 1 | Secrets | always | API keys, tokens, passwords in code | | 2 | Dependencies | always | Known vulnerabilities in packages | | 3 | OWASP | always | Injection, XSS, eval, command injection | | 4 | Infrastructure | always | CI/CD configs, cloud configs | | 5 | Attack Surface | always | Endpoints, CORS, auth patterns | | 6 | Containers | always | Dockerfile, Compose, K8s manifests | | 7 | IaC | always | Terraform, CloudFormation, Ansible | | 8 | Custom Rules | always | User-defined YAML rules (.agentsec/rules/) | | 9 | Prompt Injection | always | LLM/AI app security — OWASP LLM01-LLM10, system prompt leakage | | 10 | Taint Analysis | --advanced | Source-to-sink data flow tracking | | 11 | Prototype Pollution | --advanced | Unsafe merges, dynamic property chains | | 12 | Cryptography | --advanced | Weak algorithms, key sizes, Math.random | | 13 | Race Conditions | --advanced | TOCTOU, shared state, non-atomic ops | | 14 | Import Graph | --advanced | Circular deps, blast radius, sensitive exports | | 15 | Supply Chain | --advanced | Typosquatting, install scripts, pinning | | 16 | Code Quality | --advanced | Null safety, logic bugs, platform issues |

Standalone checks: --versions, --cve, --license, --sbom, --dast, --git-history, --dep-behavior, --reachability, --ai-code, --policy, --threat-model, --verify-secrets

AI add-ons (post-processing): --ai, --ai-fix, --ai-triage, --deep, --agent-audit

Workflow modes: --pr <n>, --monorepo, --workspace, --watch, --ci, --baseline

Performance: incremental scan cache is on by default — only modified files are re-analyzed between runs (use --no-cache to disable, --clear-cache to wipe).

LLM Providers

AI features (--ai, --deep, --ai-fix) support multiple providers:

| Provider | Flag | Env Variable | |----------|------|-------------| | Google Gemini | gemini:gemini-2.5-flash | GEMINI_API_KEY | | OpenAI | openai:gpt-4o | OPENAI_API_KEY | | Anthropic | anthropic:claude-sonnet-4-20250514 | ANTHROPIC_API_KEY | | Ollama (local) | ollama:qwen2.5:14b | — | | Groq | groq:llama-3.3-70b | GROQ_API_KEY | | Together | together:meta-llama/Llama-3-70b | TOGETHER_API_KEY |

Agent-Powered Audit

--agent-audit runs 10 specialist AI agents in parallel, each with a tailored security lens. A red team simulator then chains their findings into realistic attack paths with exploit POCs.

| # | Specialist | Focus | |---|-----------|-------| | 1 | Injection Hunter | SQLi, command, template, LDAP, XPath injection | | 2 | Auth Breaker | Bypass, privilege escalation, session/JWT attacks | | 3 | Data Leak Detective | PII in logs, verbose errors, response over-exposure | | 4 | Crypto Auditor | Weak algorithms, predictable random, timing attacks | | 5 | Race Condition Finder | TOCTOU, concurrent modification, atomicity | | 6 | Supply Chain Analyst | Unusual imports, phantom deps, install scripts | | 7 | API Security Tester | Mass assignment, rate limiting, schema validation | | 8 | Infrastructure Auditor | Secrets in CI, permissive configs, missing controls | | 9 | Business Logic Analyzer | Workflow bypass, state machine errors | | 10 | Red Team Simulator | Chains findings into attack paths + exploit POCs |

LSP Server (Editor Diagnostics)

Run the scanner as a Language Server Protocol server over stdio for real-time diagnostics in any LSP-aware editor (VS Code, Neovim, Emacs, JetBrains, Helix, …).

npx tsx src/cli/index.ts lsp                       # default debounce 300 ms
npx tsx src/cli/index.ts lsp --debounce 500
npx tsx src/cli/index.ts lsp --no-prompt-injection # skip prompt-injection scan for speed

Each didOpen / didChange event runs the scanner against the buffer and pushes findings as LSP Diagnostic messages. Severities map to LSP levels (critical/high → Error, medium → Warning, low → Information, info → Hint), and diagnostic codes carry the OWASP / CWE identifier.

Wire it up in VS Code via a generic LSP client extension, or in Neovim with vim.lsp.start({ cmd = { 'npx', 'tsx', 'src/cli/index.ts', 'lsp' } }).

Suppressions (False-Positive Allowlist)

Persist accepted-risk and false-positive decisions in .agentsec/suppressions.yml. Findings are matched by a deterministic fingerprint (rule ID + file + line + snippet hash) so they survive refactors as long as the underlying issue is unchanged.

# List active suppressions for the current project
npx tsx src/cli/index.ts suppress list

# Add — copy the fingerprint from any scan output
npx tsx src/cli/index.ts suppress add <fingerprint> \
  --title "Hardcoded test API key" \
  --reason "Test fixture, not a real secret" \
  --expires 2026-12-31

# Remove
npx tsx src/cli/index.ts suppress remove <fingerprint>

# Re-include suppressed findings in a scan (marked [SUPPRESSED])
npx tsx src/cli/index.ts scan --show-suppressed

Expired suppressions are surfaced as warnings on the next scan, forcing periodic re-review of accepted risks.

STRIDE Threat Model

--threat-model walks the codebase and emits a STRIDE-classified markdown document — assets, trust boundaries, and threats per the Microsoft STRIDE taxonomy (Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege).

npx tsx src/cli/index.ts scan --threat-model                # writes THREAT_MODEL.md
npx tsx src/cli/index.ts scan --threat-model docs/threats.md

Live Secret Verification

--verify-secrets takes every secret detected in the secrets phase and probes the issuer's API to confirm whether the key is actually live. Live keys get upgraded to critical severity; dead/revoked keys get demoted to info.

Currently supported issuers: GitHub, Stripe, Slack, OpenAI, Anthropic, SendGrid, npm, Mailgun.

npx tsx src/cli/index.ts scan --verify-secrets

Project Structure

src/
  cli/           — CLI commands (scan, chat, dashboard, run, list, lsp, suppress)
  security/      — All scanner modules (40+ files, 16 phases)
  providers/     — LLM provider adapters (7 providers)
  tools/         — Tool system (builtin + security + MCP)
  agents/        — Agent framework (claude, coordinator, worker)
  core/          — Query engine, store, events
  config/        — Configuration loader with prototype pollution protection
  plugins/       — Plugin loader and registry
test/
  security/      — Vitest fixture-based tests for scanners
  cli/           — CLI / output rendering tests
website/         — Static marketing / documentation pages

GitHub Actions

The repo includes .github/workflows/security.yml that runs on every push/PR:

• TypeScript type check
• Full --advanced security scan
• Fails the build on critical/high findings
• Uploads scan results as artifacts