AI Guard

AI Guard is a CLI-first AI security scanner for codebases and GitHub repositories.

For a full beginner step-by-step walkthrough, see docs/user-guide.md.

It detects:

• Prompt injection risk patterns
• Sensitive data exposure
• API key leakage
• Unsafe AI output handling

Install (Global Users)

Install CLI globally:

npm install -g @scan5/ai-guard

Run without global install:

npx @scan5/ai-guard --help

Install SDK in an application:

npm install @scan5/ai-guard

SDK import path:

import { AIGuardSDK } from "@scan5/ai-guard/sdk";

60-Second Quickstart

npm install
npm run build
node dist/cli.js scan ./src

Optional HTML audit report:

node dist/cli.js scan ./src --html reports/scan-report.html

Optional JSON and SARIF outputs:

node dist/cli.js scan ./src --json reports/scan-report.json --sarif reports/scan-report.sarif

CI delta mode against a baseline report:

node dist/cli.js scan ./src --baseline reports/baseline.json --ci-delta

CLI Basics

Main command

ai-guard scan <path>

<path> can be:

• Local file path
• Local directory path
• GitHub repository URL

Examples

Local scan:

ai-guard scan ./src

Scan only a subdirectory:

ai-guard scan ./repo --subdir packages/security

GitHub scan (public repository):

ai-guard scan https://github.com/owner/repo

GitHub scan with ref and subdirectory:

ai-guard scan https://github.com/owner/repo --ref main --subdir src

GitHub scan with a custom token env var:

ai-guard scan https://github.com/owner/private-repo --github-token-env TEAM_GH_TOKEN

Authenticated GitHub workflow (recommended):

ai-guard auth login
ai-guard repo list
ai-guard scan-github

This flow limits repository selection to repositories accessible by the authenticated user.

Verbose mode:

ai-guard --verbose scan ./src

Help Commands

Show top-level help:

ai-guard --help

Show help for scan command:

ai-guard help scan

Show quickstart guide:

ai-guard quickstart

Show practical usage examples:

ai-guard examples

Output

CLI output includes

• Total issues
• Severity breakdown
• File and line references
• Fix suggestions

HTML output includes

• Professional audit-style UI
• Color-coded severity
• Grouped issues
• Fix suggestions and evidence

Generate HTML report:

ai-guard scan ./src --html reports/scan-report.html

Private GitHub Repositories

AI Guard supports private repositories via token authentication.

Supported defaults:

• AI_GUARD_GITHUB_TOKEN
• GITHUB_TOKEN

Custom token env variable:

ai-guard scan https://github.com/owner/private-repo --github-token-env TEAM_GH_TOKEN

Reliability and Testing

Run all tests:

npm test

Run only unit tests:

npm run test:unit

Run only integration tests:

npm run test:integration

Benchmarking

Run scanner benchmark on src with default iterations:

npm run benchmark

Run benchmark on a custom path with explicit iterations:

npm run benchmark -- ./src 10

Unified Findings and Correlation APIs

AI Guard now includes a unified findings layer for combining static and dynamic results.

Capabilities:

• Ingestion paths for static and dynamic findings
• Fingerprint-based deduplication with stable identifiers across rescans
• Cross-plane correlation by rule family, location, and service path
• Severity promotion when both planes confirm risk
• Queryable triage views for prioritization workflows

Core modules:

• src/unified/finding-ingestion-service.ts
• src/unified/correlation-engine.ts
• src/unified/triage-query-api.ts
• src/contracts/unified-findings.ts

Typical usage flow:

1. Ingest static findings from scan output.
2. Ingest dynamic findings from runtime SDK output.
3. Query correlated and promoted findings using triage APIs.
4. Use triage view summary for dedupe reduction and cross-plane confirmation.

Exit Codes

• 0: Scan completed successfully
• 1: Runtime failure
• 2: Validation/config/input error

Troubleshooting

If a scan fails:

1. Re-run with --verbose
2. Check path/ref/subdir inputs
3. For private GitHub repos, confirm your token variable is set
4. Use ai-guard examples for working command patterns

Scale and Operations (Phase 6)

Operational docs:

• docs/operations/phase6-capacity-planning.md
• docs/operations/phase6-load-test-results.json
• docs/operations/phase6-failure-runbook.md
• docs/operations/phase7-compliance-configuration.md

Run the Phase 6 load benchmark:

npm run benchmark:phase6