sync: update from internal repo (2026-02-15 20:31)

Author: Traviseric

README.md

@@ -4,10 +4,49 @@
 [![npm version](https://img.shields.io/npm/v/@empowered-humanity/agent-security)](https://www.npmjs.com/package/@empowered-humanity/agent-security)
 [![License: MIT](https://img.shields.io/badge/License-MIT-gold.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/Tests-123%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/Tests-126%20passing-brightgreen.svg)]()
 [![Patterns](https://img.shields.io/badge/Patterns-190-navy.svg)]()
 
-Security scanner for AI agent architectures. Detects prompt injection, credential exposure, code injection, and agent-specific attack patterns.
+Static analysis security scanner purpose-built for AI agent architectures. Detects prompt injection, credential exposure, MCP server misconfigurations, code injection, and agent-specific attack patterns across your codebase -- before they reach production.
+
+![CLI Demo](docs/demo.gif)
+
+## Quick Start
+
+```bash
+# 1. Install
+npm install @empowered-humanity/agent-security
+
+# 2. Scan
+npx @empowered-humanity/agent-security scan ./my-agent
+
+# 3. Review findings in your terminal, or export SARIF for GitHub Code Scanning
+npx @empowered-humanity/agent-security scan ./my-agent --format sarif --output results.sarif
+```
+
+## How It Compares
+
+| Capability | **agent-security** | Semgrep (LLM rules) | Garak (NVIDIA) | LLM Guard (Protect AI) |
+|---|---|---|---|---|
+| **Focus** | Static analysis of AI agent code & prompts | General-purpose SAST with some AI/LLM rules | Runtime red-teaming of live LLM endpoints | Runtime input/output guardrails for LLM apps |
+| **AI agent-specific patterns** | 190 | Limited (general injection rules; no agent-specific categories) | N/A (probes live models, not source code) | N/A (runtime scanner, not static analysis) |
+| **OWASP Agentic Top 10 (ASI01-ASI10)** | All 10 categories, 65 patterns | Not covered | Not covered (maps to OWASP LLM Top 10, not Agentic) | Not covered |
+| **MCP security patterns** | 44 patterns (SlowMist checklist) | N/A | N/A | N/A |
+| **SARIF output** | Yes (v2.1.0, GitHub Code Scanning) | Yes | No (JSON/HTML reports) | No |
+| **GitHub Action** | Yes (built-in `action.yml`) | Yes (`semgrep/semgrep-action`) | No | No |
+| **pre-commit hook** | Yes (built-in `.pre-commit-hooks.yaml`) | Yes | No | No |
+| **CWE mappings** | Yes (30+ categories mapped) | Yes | Limited (references CWE-1426 for prompt injection) | No |
+| **Taint analysis** | Yes (proximity-based) | Yes (cross-file dataflow in Pro) | No | No |
+| **Free / open-source** | Yes (MIT) | Community edition free; Pro is paid | Yes (Apache 2.0) | Yes (MIT) |
+
+**When to use each tool:**
+
+- **agent-security** -- You are building an AI agent (MCP servers, multi-agent systems, RAG pipelines, LLM-powered tools) and need to catch vulnerabilities in your code, configs, and prompts before deployment.
+- **Semgrep** -- You need general-purpose SAST across your full application stack (not agent-specific).
+- **Garak** -- You want to red-team a live LLM endpoint by sending adversarial probes and measuring model responses.
+- **LLM Guard** -- You need runtime input/output filtering to sanitize prompts and responses in production.
+
+These tools are complementary. Use agent-security in CI to catch static vulnerabilities, Garak to probe your deployed model, and LLM Guard as a runtime guardrail.
 
 ## What It Detects
 
@@ -78,14 +117,42 @@ The scanner implements detection for all 10 OWASP Agentic Security Issues:
 npm install @empowered-humanity/agent-security
 ```
 
-## Quick Start
+## CLI Usage
 
 ### Scan a Codebase
 
 ```bash
 npx @empowered-humanity/agent-security scan ./my-agent
 ```
 
+### Common Options
+
+```bash
+# Set minimum severity threshold
+npx @empowered-humanity/agent-security scan . --severity high
+
+# Export as SARIF for GitHub Code Scanning
+npx @empowered-humanity/agent-security scan . --format sarif --output results.sarif
+
+# Export as JSON
+npx @empowered-humanity/agent-security scan . --format json --output results.json
+
+# Fail CI if critical findings exist
+npx @empowered-humanity/agent-security scan . --fail-on critical
+
+# Filter by OWASP ASI category
+npx @empowered-humanity/agent-security scan . --asi ASI06
+
+# Group findings by classification
+npx @empowered-humanity/agent-security scan . --group classification
+
+# List all patterns
+npx @empowered-humanity/agent-security patterns
+
+# Show statistics
+npx @empowered-humanity/agent-security stats
+```
+
 ### Scan from Node.js
 
 ```javascript
@@ -124,26 +191,69 @@ te-agent-security scan ./my-agent --group classification
 ```
 
 ### Test File Severity Downgrade
-Findings in test/fixture/example/payload directories are automatically severity-downgraded (critical→high, high→medium) since they represent lower risk.
+Findings in test/fixture/example/payload directories are automatically severity-downgraded (critical->high, high->medium) since they represent lower risk.
 
 ### Taint Proximity Analysis
 For dangerous sinks (eval, exec, pickle), the scanner checks whether user input sources (input(), request, argv, LLM .invoke()) are within 10 lines. Direct taint escalates severity to critical.
 
 ### Context Flow Tracing
-Detects when serialized conversation context (JSON.stringify of messages/history) flows to external API calls — a novel agent-specific attack surface.
+Detects when serialized conversation context (JSON.stringify of messages/history) flows to external API calls -- a novel agent-specific attack surface.
 
 ```javascript
 // Each finding includes intelligence data:
 finding.classification    // 'live_vulnerability' | 'test_payload' | ...
 finding.isTestFile        // true if in test/fixture/example directory
 finding.taintProximity    // 'direct' | 'nearby' | 'distant'
-finding.contextFlowChain  // serialization → external call chain
+finding.contextFlowChain  // serialization -> external call chain
 finding.severityDowngraded // true if test file downgrade applied
 ```
 
+## GitHub Action
+
+Use the built-in `action.yml` to add agent security scanning to any GitHub repository:
+
+```yaml
+name: Agent Security Scan
+
+on: [pull_request]
+
+jobs:
+  agent-security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: empowered-humanity/agent-security@v1
+        with:
+          path: '.'
+          severity: 'medium'
+          fail-on-findings: 'high'
+          upload-sarif: 'true'
+```
+
+### Action Inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `path` | `.` | Path to scan |
+| `severity` | `medium` | Minimum severity to report (`critical`, `high`, `medium`, `low`) |
+| `format` | `sarif` | Output format (`console`, `json`, `sarif`) |
+| `fail-on-findings` | `high` | Fail if findings at or above this severity |
+| `upload-sarif` | `true` | Upload SARIF results to GitHub Code Scanning |
+
+### Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `findings-count` | Total number of findings |
+| `risk-level` | Overall risk level |
+| `sarif-file` | Path to SARIF output file |
+
+When `upload-sarif` is enabled, findings appear directly in the GitHub Security tab under Code Scanning alerts.
+
 ## CI/CD Integration
 
-### GitHub Actions
+### GitHub Actions (inline)
 
 ```yaml
 name: Agent Security Scan
@@ -163,7 +273,17 @@ jobs:
 
 ### Pre-commit Hook
 
-Add to `.git/hooks/pre-commit`:
+Add to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/empowered-humanity/agent-security
+    rev: v1.2.0
+    hooks:
+      - id: agent-security-scan
+```
+
+Or add directly to `.git/hooks/pre-commit`:
 
 ```bash
 #!/bin/bash
@@ -297,6 +417,17 @@ const jsonReporter = new JsonReporter();
 const json = jsonReporter.report(result);
 ```
 
+### SARIF Reporter
+
+```typescript
+import { formatAsSarif } from '@empowered-humanity/agent-security/reporters';
+
+// Generate SARIF 2.1.0 output with CWE mappings
+const sarifJson = formatAsSarif(result, process.cwd());
+
+// Upload to GitHub Code Scanning, or integrate with any SARIF-compatible tool
+```
+
 ## Examples
 
 See the [`examples/`](./examples) directory for complete usage examples:

action.yml

@@ -1,5 +1,5 @@
 name: 'Agent Security Scan'
-description: 'Scan for AI agent security vulnerabilities with 176+ detection patterns'
+description: 'Scan for AI agent security vulnerabilities with 190+ detection patterns covering OWASP ASI Top 10, MCP security, and credential exposure'
 author: 'Empowered Humanity'
 
 inputs:

src/reporters/sarif.ts

@@ -3,14 +3,66 @@
  *
  * Outputs scan results in SARIF 2.1.0 format for GitHub Code Scanning
  * and other SARIF-compatible tools.
+ *
+ * Features:
+ * - CWE ID mappings for all attack categories
+ * - OWASP ASI tags on rules
+ * - GitHub Security tab integration
  */
 
-import type { Finding, ScanResult, Severity } from '../patterns/types.js';
+import type { AttackCategory, Finding, ScanResult, Severity } from '../patterns/types.js';
 
-const VERSION = '1.1.0';
+const VERSION = '1.2.0';
 const SCHEMA_URI = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
 const INFORMATION_URI = 'https://github.com/empowered-humanity/agent-security';
 
+/**
+ * Map attack categories to CWE IDs.
+ * Uses the most specific applicable CWE for each category.
+ */
+const CATEGORY_CWE_MAP: Partial<Record<AttackCategory, string>> = {
+  instruction_override: 'CWE-74',    // Injection
+  role_manipulation: 'CWE-284',      // Improper Access Control
+  boundary_escape: 'CWE-116',        // Improper Encoding or Escaping
+  data_exfiltration: 'CWE-200',      // Information Exposure
+  hidden_injection: 'CWE-94',        // Code Injection
+  stealth_instruction: 'CWE-94',
+  url_reconstruction: 'CWE-601',     // Open Redirect
+  credential_theft: 'CWE-522',       // Insufficiently Protected Credentials
+  credential_exposure: 'CWE-798',    // Hardcoded Credentials
+  cross_agent_escalation: 'CWE-269', // Improper Privilege Management
+  mcp_attack: 'CWE-346',            // Origin Validation Error
+  rag_poisoning: 'CWE-94',
+  persistence: 'CWE-506',           // Embedded Malicious Code
+  goal_hijacking: 'CWE-74',
+  session_smuggling: 'CWE-384',     // Session Fixation
+  argument_injection: 'CWE-88',     // Argument Injection
+  code_injection: 'CWE-94',
+  ssrf: 'CWE-918',                  // SSRF
+  reconnaissance: 'CWE-200',
+  prompt_extraction: 'CWE-200',
+  defense_evasion: 'CWE-693',       // Protection Mechanism Failure
+  hierarchy_violation: 'CWE-269',
+  adversarial_suffix: 'CWE-74',
+  ASI01_goal_hijack: 'CWE-74',
+  ASI02_tool_misuse: 'CWE-269',
+  ASI03_privilege_abuse: 'CWE-269',
+  ASI04_supply_chain: 'CWE-494',    // Download Without Integrity Check
+  ASI05_rce: 'CWE-94',
+  ASI06_memory_poisoning: 'CWE-471', // Modification of Assumed-Immutable Data
+  ASI07_insecure_comms: 'CWE-319',  // Cleartext Transmission
+  ASI08_cascading_failures: 'CWE-400', // Uncontrolled Resource Consumption
+  ASI09_trust_exploitation: 'CWE-290', // Auth Bypass by Spoofing
+  ASI10_rogue_agents: 'CWE-506',
+  config_vulnerability: 'CWE-16',   // Configuration
+  permission_escalation: 'CWE-269',
+  behavior_manipulation: 'CWE-74',
+  platform_specific: 'CWE-74',
+  rendering_exfil: 'CWE-200',
+  path_traversal: 'CWE-22',
+  dangerous_commands: 'CWE-78',     // OS Command Injection
+};
+
 interface SarifMessage {
   text: string;
 }
@@ -46,6 +98,7 @@ interface SarifRule {
   id: string;
   shortDescription: SarifMessage;
   fullDescription?: SarifMessage;
+  helpUri?: string;
   defaultConfiguration?: {
     level: 'error' | 'warning' | 'note' | 'none';
   };
@@ -105,6 +158,14 @@ function normalizeUri(filePath: string, baseDir?: string): string {
   return uri.replace(/\\/g, '/');
 }
 
+/**
+ * Get the CWE ID for a finding, checking pattern.cwe first then category mapping
+ */
+function getCweId(finding: Finding): string | undefined {
+  if (finding.pattern.cve) return undefined; // cve is separate
+  return CATEGORY_CWE_MAP[finding.pattern.category];
+}
+
 /**
  * Build deduplicated SARIF rules from findings
  */
@@ -115,16 +176,32 @@ function buildRules(findings: Finding[]): SarifRule[] {
     const id = finding.pattern.name;
     if (seen.has(id)) continue;
 
+    const cweId = getCweId(finding);
+    const tags: string[] = [];
+    if (cweId) tags.push(cweId);
+    if (finding.pattern.owaspAsi) tags.push(`OWASP-${finding.pattern.owaspAsi}`);
+    tags.push(`security`);
+
     const rule: SarifRule = {
       id,
       shortDescription: { text: finding.pattern.description },
       defaultConfiguration: {
         level: severityToLevel(finding.pattern.severity),
       },
+      properties: {
+        tags,
+        ...(finding.pattern.owaspAsi && { owaspAsi: finding.pattern.owaspAsi }),
+        ...(cweId && { cweId }),
+      },
     };
 
-    if (finding.pattern.owaspAsi) {
-      rule.properties = { owaspAsi: finding.pattern.owaspAsi };
+    if (cweId) {
+      const cweNum = cweId.replace('CWE-', '');
+      rule.helpUri = `https://cwe.mitre.org/data/definitions/${cweNum}.html`;
+    }
+
+    if (finding.pattern.remediation) {
+      rule.fullDescription = { text: finding.pattern.remediation };
     }
 
     seen.set(id, rule);

tests/sarif-reporter.test.ts

@@ -61,7 +61,7 @@ describe('SARIF Reporter', () => {
     expect(sarif.version).toBe('2.1.0');
     expect(sarif.runs).toHaveLength(1);
     expect(sarif.runs[0].tool.driver.name).toBe('agent-security');
-    expect(sarif.runs[0].tool.driver.semanticVersion).toBe('1.1.0');
+    expect(sarif.runs[0].tool.driver.semanticVersion).toBe('1.2.0');
   });
 
   it('maps critical/high to error, medium to warning, low to note', () => {
@@ -111,6 +111,47 @@ describe('SARIF Reporter', () => {
     expect(props.contextFlowChain).toEqual(['source', 'sink']);
   });
 
+  it('maps attack categories to CWE IDs in rule properties', () => {
+    const finding = makeFinding({
+      pattern: makePattern({ category: 'credential_exposure', name: 'cred-test' }),
+    });
+    const result = makeScanResult([finding]);
+    const sarif = JSON.parse(formatAsSarif(result));
+    const rule = sarif.runs[0].tool.driver.rules[0];
+
+    expect(rule.properties.cweId).toBe('CWE-798');
+    expect(rule.properties.tags).toContain('CWE-798');
+    expect(rule.properties.tags).toContain('security');
+    expect(rule.helpUri).toBe('https://cwe.mitre.org/data/definitions/798.html');
+  });
+
+  it('includes OWASP ASI tag in rule tags', () => {
+    const finding = makeFinding({
+      pattern: makePattern({ category: 'ASI01_goal_hijack', owaspAsi: 'ASI01', name: 'asi-test' }),
+    });
+    const result = makeScanResult([finding]);
+    const sarif = JSON.parse(formatAsSarif(result));
+    const rule = sarif.runs[0].tool.driver.rules[0];
+
+    expect(rule.properties.tags).toContain('CWE-74');
+    expect(rule.properties.tags).toContain('OWASP-ASI01');
+    expect(rule.properties.owaspAsi).toBe('ASI01');
+  });
+
+  it('includes remediation as fullDescription when available', () => {
+    const finding = makeFinding({
+      pattern: makePattern({
+        name: 'remed-test',
+        remediation: 'Use environment variables for secrets',
+      }),
+    });
+    const result = makeScanResult([finding]);
+    const sarif = JSON.parse(formatAsSarif(result));
+    const rule = sarif.runs[0].tool.driver.rules[0];
+
+    expect(rule.fullDescription.text).toBe('Use environment variables for secrets');
+  });
+
   it('produces zero results for empty findings', () => {
     const result = makeScanResult([]);
     const sarif = JSON.parse(formatAsSarif(result));