scan5 0.1.0

Production-grade AI security scanner with plugin-based detections

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

# Enterprise pipeline outputs
node dist/cli.js scan ./src \
	--gitlab-sast reports/gl-sast-report.json \
	--siem-json reports/siem-findings.ndjson

CI delta mode against a baseline report:

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

CLI Basics

Subscription plans and enforcement

AI Guard enforces plan-based access locally.

• free: local scans only, no GitHub scan commands, no --ci-delta
• pro: GitHub scanning and --ci-delta enabled
• team: higher monthly quota
• enterprise: unlimited quota

Check and set plan:

ai-guard subscription status
ai-guard subscription set --plan pro

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

## Enterprise Integrations

### GitHub Advanced Security

- CI workflow includes SARIF upload via `github/codeql-action/upload-sarif@v3`.
- Generated SARIF carries OWASP/NIST/EU compliance metadata per rule.

### GitLab SAST

- Generate GitLab SAST report:

```bash
ai-guard scan ./src --gitlab-sast gl-sast-report.json

• Use .gitlab-ci.yml template in repository root.

SIEM (Splunk / Datadog / Elastic ECS)

• Generate ECS-compatible NDJSON events:

ai-guard scan ./src --siem-json reports/siem-findings.ndjson

Pre-commit hook (staged-only)

• Package: packages/ai-guard-pre-commit
• Scope: local workspace helper (not published as a standalone npm package)
• Hook command (published CLI): npx @scan5/ai-guard scan ./src
• Scans staged snapshot only for fast feedback.

Semgrep export

• Rules file: rules/semgrep/ai-guard-rules.yml
• Load directly in existing Semgrep pipelines.

VS Code Language Server extension

• Package: packages/vscode-ai-guard-extension
• Inline diagnostics for:
  • hardcoded system prompts
  • missing input sanitization
  • unvalidated tool args
• Quick fixes included for common remediation paths.

## Private GitHub Repositories

AI Guard supports private repositories via token authentication.

Supported defaults:

- `AI_GUARD_GITHUB_TOKEN`
- `GITHUB_TOKEN`

Custom token env variable:

```bash
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