Package Exports

@agentsec/cli
@agentsec/cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@agentsec/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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