@authora/agent-audit 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npx tsc
+
+      - name: Publish
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 Authora
+
+Permission is hereby granted...

package/README.md

@@ -0,0 +1,90 @@
+# agent-audit
+
+> Security scanner for AI agents. Find vulnerabilities in your agent setup in 30 seconds.
+
+```bash
+npx agent-audit
+```
+
+## What it checks
+
+| Category | What it finds |
+|----------|--------------|
+| **Credentials** | Shared API keys across agents, hardcoded secrets in code |
+| **Identity** | Missing agent identity layer, no cryptographic verification |
+| **MCP** | MCP servers without authentication, unprotected tool endpoints |
+| **Permissions** | Overly broad agent permissions, admin/root access |
+| **Delegation** | Missing delegation chains, agents inheriting full user permissions |
+| **Audit** | No audit logging for agent actions |
+| **Approvals** | No human-in-the-loop for sensitive operations |
+| **Resilience** | Missing timeouts, no error handling on tool calls |
+
+## Output
+
+```
+  Agent Security Audit
+  by Authora -- https://authora.dev
+
+  Scanning current directory...
+
+  Scanned 47 files
+  Found 3 agent(s), 2 MCP server(s)
+
+  CRITICAL  Shared API key may be used by 3 agent files (.env)
+  CRITICAL  No agent identity layer detected
+  CRITICAL  2 MCP server(s) found but no agent identity
+  WARNING   MCP server detected without visible auth configuration (mcp/server.ts)
+  WARNING   No delegation chains -- agents may inherit unlimited permissions
+  WARNING   No audit logging for agent actions detected
+  INFO      No approval workflows for sensitive agent actions
+
+  Security Posture:
+    Identity layer:     No
+    Delegation chains:  No
+    Audit logging:      No
+    Approval workflows: No
+
+  Agent Security Score: 1.5/10  [===                     ]  Grade: F
+  3 critical, 3 warnings
+
+  Learn more: https://github.com/authora-dev/awesome-agent-security
+  Fix issues: https://authora.dev/get-started
+```
+
+## Options
+
+```bash
+npx agent-audit [directory]     # Scan a specific directory
+npx agent-audit --json          # Output as JSON
+npx agent-audit --badge         # Generate README badge markdown
+```
+
+## Badge
+
+Add a security badge to your README:
+
+```markdown
+![Agent Security: A](https://img.shields.io/badge/Agent_Security-A-brightgreen)
+```
+
+## What scores mean
+
+| Score | Grade | Meaning |
+|-------|-------|---------|
+| 9-10 | A+ | Excellent -- cryptographic identity, delegation, audit, approvals |
+| 8 | A | Strong -- identity layer present, minor gaps |
+| 7 | B+ | Good -- most practices in place |
+| 6 | B | Decent -- some security measures, gaps remain |
+| 5 | C | Needs work -- basic security only |
+| 3-4 | D | Weak -- significant vulnerabilities |
+| 0-2 | F | Critical -- no agent security measures |
+
+## Learn more
+
+- [Awesome Agent Security](https://github.com/authora-dev/awesome-agent-security) -- curated resources
+- [Authora](https://authora.dev) -- identity, coordination, and security for AI agents
+- [Authora Docs](https://authora.dev/developers/quickstart) -- get started in 5 minutes
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { scanDirectory } from "./scanner.js";
+import { formatReport } from "./reporter.js";
+const args = process.argv.slice(2);
+const targetDir = args[0] ?? ".";
+const jsonOutput = args.includes("--json");
+const badgeOutput = args.includes("--badge");
+async function main() {
+    if (!jsonOutput) {
+        console.log("");
+        console.log("  \x1b[1m\x1b[36mAgent Security Audit\x1b[0m");
+        console.log("  \x1b[90mby Authora -- https://authora.dev\x1b[0m");
+        console.log("");
+        console.log(`  Scanning ${targetDir === "." ? "current directory" : targetDir}...`);
+        console.log("");
+    }
+    const findings = await scanDirectory(targetDir);
+    if (jsonOutput) {
+        console.log(JSON.stringify(findings, null, 2));
+        return;
+    }
+    const report = formatReport(findings);
+    console.log(report);
+    if (badgeOutput) {
+        const score = findings.score;
+        const color = score >= 8 ? "brightgreen" : score >= 6 ? "yellow" : score >= 4 ? "orange" : "red";
+        const grade = score >= 9 ? "A+" : score >= 8 ? "A" : score >= 7 ? "B+" : score >= 6 ? "B" : score >= 5 ? "C" : score >= 3 ? "D" : "F";
+        console.log("");
+        console.log(`  \x1b[1mREADME Badge:\x1b[0m`);
+        console.log(`  ![Agent Security: ${grade}](https://img.shields.io/badge/Agent_Security-${grade}-${color})`);
+    }
+    process.exit(findings.score >= 6 ? 0 : 1);
+}
+main().catch((err) => {
+    console.error("  \x1b[31mError:\x1b[0m", err.message);
+    process.exit(2);
+});

package/dist/reporter.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "./scanner.js";
+export declare function formatReport(result: ScanResult): string;

package/dist/reporter.js

@@ -0,0 +1,77 @@
+const COLORS = {
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+    white: "\x1b[37m",
+    bold: "\x1b[1m",
+    reset: "\x1b[0m",
+};
+const SEVERITY_LABEL = {
+    critical: `${COLORS.red}${COLORS.bold}CRITICAL${COLORS.reset}`,
+    warning: `${COLORS.yellow}WARNING ${COLORS.reset}`,
+    info: `${COLORS.cyan}INFO    ${COLORS.reset}`,
+    pass: `${COLORS.green}PASS    ${COLORS.reset}`,
+};
+function scoreBar(score) {
+    const filled = Math.round(score * 2);
+    const empty = 20 - filled;
+    const color = score >= 8 ? COLORS.green : score >= 5 ? COLORS.yellow : COLORS.red;
+    return `${color}[${"=".repeat(filled)}${" ".repeat(empty)}]${COLORS.reset}`;
+}
+function gradeFromScore(score) {
+    if (score >= 9)
+        return `${COLORS.green}${COLORS.bold}A+${COLORS.reset}`;
+    if (score >= 8)
+        return `${COLORS.green}${COLORS.bold}A${COLORS.reset}`;
+    if (score >= 7)
+        return `${COLORS.green}B+${COLORS.reset}`;
+    if (score >= 6)
+        return `${COLORS.yellow}B${COLORS.reset}`;
+    if (score >= 5)
+        return `${COLORS.yellow}C${COLORS.reset}`;
+    if (score >= 3)
+        return `${COLORS.red}D${COLORS.reset}`;
+    return `${COLORS.red}${COLORS.bold}F${COLORS.reset}`;
+}
+export function formatReport(result) {
+    const lines = [];
+    // Summary
+    lines.push(`  ${COLORS.gray}Scanned ${result.scannedFiles} files${COLORS.reset}`);
+    lines.push(`  ${COLORS.gray}Found ${result.agents} agent(s), ${result.mcpServers} MCP server(s)${COLORS.reset}`);
+    lines.push("");
+    // Findings
+    if (result.findings.length === 0) {
+        lines.push(`  ${COLORS.green}${COLORS.bold}No issues found!${COLORS.reset}`);
+    }
+    else {
+        for (const f of result.findings) {
+            const label = SEVERITY_LABEL[f.severity] ?? f.severity;
+            const file = f.file ? ` ${COLORS.gray}(${f.file})${COLORS.reset}` : "";
+            lines.push(`  ${label}  ${f.message}${file}`);
+            if (f.fix) {
+                lines.push(`           ${COLORS.gray}Fix: ${f.fix}${COLORS.reset}`);
+            }
+        }
+    }
+    lines.push("");
+    // Security posture
+    lines.push(`  ${COLORS.bold}Security Posture:${COLORS.reset}`);
+    lines.push(`    Identity layer:    ${result.hasIdentityLayer ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.red}No${COLORS.reset}`}`);
+    lines.push(`    Delegation chains: ${result.hasDelegation ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.red}No${COLORS.reset}`}`);
+    lines.push(`    Audit logging:     ${result.hasAuditLog ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.red}No${COLORS.reset}`}`);
+    lines.push(`    Approval workflows:${result.hasApprovals ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.yellow} No${COLORS.reset}`}`);
+    lines.push("");
+    // Score
+    const criticals = result.findings.filter((f) => f.severity === "critical").length;
+    const warnings = result.findings.filter((f) => f.severity === "warning").length;
+    lines.push(`  ${COLORS.bold}Agent Security Score: ${result.score}/10${COLORS.reset}  ${scoreBar(result.score)}  Grade: ${gradeFromScore(result.score)}`);
+    lines.push(`  ${COLORS.gray}${criticals} critical, ${warnings} warnings${COLORS.reset}`);
+    lines.push("");
+    // CTAs
+    lines.push(`  ${COLORS.gray}Learn more:${COLORS.reset} https://github.com/authora-dev/awesome-agent-security`);
+    lines.push(`  ${COLORS.gray}Fix issues:${COLORS.reset} https://authora.dev/get-started`);
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/scanner.d.ts

@@ -0,0 +1,20 @@
+export interface Finding {
+    severity: "critical" | "warning" | "info" | "pass";
+    category: string;
+    message: string;
+    file?: string;
+    line?: number;
+    fix?: string;
+}
+export interface ScanResult {
+    findings: Finding[];
+    score: number;
+    agents: number;
+    mcpServers: number;
+    hasIdentityLayer: boolean;
+    hasDelegation: boolean;
+    hasAuditLog: boolean;
+    hasApprovals: boolean;
+    scannedFiles: number;
+}
+export declare function scanDirectory(dir: string): Promise<ScanResult>;

package/dist/scanner.js

@@ -0,0 +1,234 @@
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, extname } from "path";
+const CODE_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".go", ".rs", ".java", ".rb",
+    ".json", ".yaml", ".yml", ".toml", ".env",
+]);
+const MAX_FILES = 500;
+const MAX_FILE_SIZE = 100_000; // 100KB
+function walkDir(dir, files = [], depth = 0) {
+    if (depth > 8 || files.length > MAX_FILES)
+        return files;
+    try {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" ||
+                entry === "build" || entry === "__pycache__" || entry === "venv" ||
+                entry === ".git" || entry === "vendor")
+                continue;
+            const fullPath = join(dir, entry);
+            try {
+                const stat = statSync(fullPath);
+                if (stat.isDirectory()) {
+                    walkDir(fullPath, files, depth + 1);
+                }
+                else if (stat.isFile() && CODE_EXTENSIONS.has(extname(entry)) && stat.size < MAX_FILE_SIZE) {
+                    files.push(fullPath);
+                }
+            }
+            catch {
+                // Skip inaccessible files
+            }
+        }
+    }
+    catch {
+        // Skip inaccessible directories
+    }
+    return files;
+}
+function readFile(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+export async function scanDirectory(dir) {
+    const findings = [];
+    let agents = 0;
+    let mcpServers = 0;
+    let hasIdentityLayer = false;
+    let hasDelegation = false;
+    let hasAuditLog = false;
+    let hasApprovals = false;
+    const files = walkDir(dir);
+    for (const file of files) {
+        const content = readFile(file);
+        if (!content)
+            continue;
+        const lower = content.toLowerCase();
+        const relPath = file.replace(dir + "/", "");
+        // Detect agents
+        if (/\bagent\b/i.test(content) && (/\bcreate.*agent|agent.*config|new.*agent|agent.*class\b/i.test(content))) {
+            agents++;
+        }
+        // Detect MCP servers
+        if (/mcp.*server|mcpserver|model.*context.*protocol/i.test(lower)) {
+            mcpServers++;
+        }
+        // Check for identity layer
+        if (/authora|@authora\/sdk|agent.*identity|ed25519.*agent|agent.*keypair/i.test(lower)) {
+            hasIdentityLayer = true;
+        }
+        // Check for delegation
+        if (/delegation.*chain|delegate.*permission|token.*exchange|rfc.*8693/i.test(lower)) {
+            hasDelegation = true;
+        }
+        // Check for audit logging
+        if (/audit.*log|agent.*audit|action.*log.*agent/i.test(lower)) {
+            hasAuditLog = true;
+        }
+        // Check for approvals
+        if (/approval.*workflow|human.*in.*loop|require.*approval/i.test(lower)) {
+            hasApprovals = true;
+        }
+        // --- CRITICAL: Shared API keys ---
+        const apiKeyPattern = /(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|AZURE_API_KEY|API_KEY)\s*[=:]\s*["']?[A-Za-z0-9_-]{20,}/g;
+        const envFile = extname(file) === ".env";
+        if (envFile) {
+            const keys = content.match(apiKeyPattern);
+            if (keys && keys.length > 0) {
+                // Check if multiple agents might share this key
+                const agentFiles = files.filter((f) => {
+                    const fc = readFile(f);
+                    return /\bagent\b/i.test(fc) && /API_KEY|api_key|apiKey/i.test(fc);
+                });
+                if (agentFiles.length > 1) {
+                    findings.push({
+                        severity: "critical",
+                        category: "credentials",
+                        message: `Shared API key may be used by ${agentFiles.length} agent files`,
+                        file: relPath,
+                        fix: "Give each agent its own credentials with scoped permissions",
+                    });
+                }
+            }
+        }
+        // --- CRITICAL: Hardcoded secrets in code ---
+        if (!envFile) {
+            const hardcodedSecrets = content.match(/(?:sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|xoxb-[0-9]+-[a-zA-Z0-9]+)/g);
+            if (hardcodedSecrets) {
+                findings.push({
+                    severity: "critical",
+                    category: "credentials",
+                    message: `Hardcoded secret found in source code`,
+                    file: relPath,
+                    fix: "Move secrets to environment variables and use a secrets manager",
+                });
+            }
+        }
+        // --- WARNING: MCP server without auth ---
+        if (/mcp.*server|createServer/i.test(content) && !/auth|authentication|authorization|token|apiKey/i.test(content)) {
+            findings.push({
+                severity: "warning",
+                category: "mcp",
+                message: "MCP server detected without visible auth configuration",
+                file: relPath,
+                fix: "Add authentication to your MCP server (API key, JWT, or Ed25519 signature verification)",
+            });
+        }
+        // --- WARNING: Broad agent permissions ---
+        if (/\*.*permission|admin.*role|full.*access|sudo|root/i.test(content) && /agent/i.test(content)) {
+            findings.push({
+                severity: "warning",
+                category: "permissions",
+                message: "Agent may have overly broad permissions",
+                file: relPath,
+                fix: "Apply least-privilege: give agents only the permissions they need for their specific task",
+            });
+        }
+        // --- WARNING: No error handling on tool calls ---
+        if (/tool.*call|callTool|execute.*tool/i.test(content) && !/try|catch|error/i.test(content)) {
+            findings.push({
+                severity: "warning",
+                category: "resilience",
+                message: "Agent tool calls without error handling",
+                file: relPath,
+                fix: "Wrap tool calls in try/catch with proper error reporting and fallback behavior",
+            });
+        }
+        // --- INFO: Agent without timeout ---
+        if (/agent/i.test(content) && /async|await|fetch|request/i.test(content) && !/timeout|AbortSignal|signal/i.test(content)) {
+            findings.push({
+                severity: "info",
+                category: "resilience",
+                message: "Agent operations without timeout -- could run indefinitely",
+                file: relPath,
+                fix: "Add timeouts to agent operations to prevent runaway processes",
+            });
+        }
+    }
+    // --- Structural findings ---
+    if (!hasIdentityLayer) {
+        findings.push({
+            severity: "critical",
+            category: "identity",
+            message: "No agent identity layer detected",
+            fix: "Add cryptographic agent identities so each agent has a verifiable, unique identity. See: https://authora.dev/get-started",
+        });
+    }
+    if (!hasDelegation && agents > 1) {
+        findings.push({
+            severity: "warning",
+            category: "delegation",
+            message: "No delegation chains -- agents may inherit unlimited permissions",
+            fix: "Implement delegation chains (RFC 8693) so agents receive scoped, time-bound authority",
+        });
+    }
+    if (!hasAuditLog) {
+        findings.push({
+            severity: "warning",
+            category: "audit",
+            message: "No audit logging for agent actions detected",
+            fix: "Log every agent action with: who (agent ID), what (action), when (timestamp), authorized by (delegation chain)",
+        });
+    }
+    if (!hasApprovals && agents > 0) {
+        findings.push({
+            severity: "info",
+            category: "approvals",
+            message: "No approval workflows for sensitive agent actions",
+            fix: "Add human-in-the-loop approval for high-risk operations (production deploys, data access, secret rotation)",
+        });
+    }
+    if (mcpServers > 0 && !hasIdentityLayer) {
+        findings.push({
+            severity: "critical",
+            category: "mcp",
+            message: `${mcpServers} MCP server(s) found but no agent identity -- any client can call any tool`,
+            fix: "Add agent identity verification to your MCP servers. See: https://authora.dev/developers/mcp",
+        });
+    }
+    // Calculate score (0-10) based on CATEGORIES not raw count
+    // This prevents large codebases from being penalized for having many files
+    const criticalCategories = new Set(findings.filter((f) => f.severity === "critical").map((f) => f.category));
+    const warningCategories = new Set(findings.filter((f) => f.severity === "warning").map((f) => f.category));
+    const infoCategories = new Set(findings.filter((f) => f.severity === "info").map((f) => f.category));
+    let score = 10;
+    score -= criticalCategories.size * 2.5;
+    score -= warningCategories.size * 1.5;
+    score -= infoCategories.size * 0.5;
+    // Bonus for good practices (max +4)
+    if (hasIdentityLayer)
+        score += 1;
+    if (hasDelegation)
+        score += 1;
+    if (hasAuditLog)
+        score += 1;
+    if (hasApprovals)
+        score += 1;
+    score = Math.max(0, Math.min(10, Math.round(score * 10) / 10));
+    return {
+        findings,
+        score,
+        agents,
+        mcpServers,
+        hasIdentityLayer,
+        hasDelegation,
+        hasAuditLog,
+        hasApprovals,
+        scannedFiles: files.length,
+    };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@authora/agent-audit",
+  "version": "0.1.0",
+  "description": "Security scanner for AI agents. Find vulnerabilities in your agent setup in 30 seconds.",
+  "bin": {
+    "agent-audit": "./dist/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js"
+  },
+  "keywords": [
+    "ai-agents",
+    "security",
+    "audit",
+    "mcp",
+    "agent-identity",
+    "llm-security",
+    "ai-security"
+  ],
+  "author": "Authora <admin@authora.dev> (https://authora.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/authora-dev/agent-audit"
+  },
+  "homepage": "https://authora.dev",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { scanDirectory } from "./scanner.js";
+import { formatReport } from "./reporter.js";
+
+const args = process.argv.slice(2);
+const targetDir = args[0] ?? ".";
+const jsonOutput = args.includes("--json");
+const badgeOutput = args.includes("--badge");
+
+async function main() {
+  if (!jsonOutput) {
+    console.log("");
+    console.log("  \x1b[1m\x1b[36mAgent Security Audit\x1b[0m");
+    console.log("  \x1b[90mby Authora -- https://authora.dev\x1b[0m");
+    console.log("");
+    console.log(`  Scanning ${targetDir === "." ? "current directory" : targetDir}...`);
+    console.log("");
+  }
+
+  const findings = await scanDirectory(targetDir);
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(findings, null, 2));
+    return;
+  }
+
+  const report = formatReport(findings);
+  console.log(report);
+
+  if (badgeOutput) {
+    const score = findings.score;
+    const color = score >= 8 ? "brightgreen" : score >= 6 ? "yellow" : score >= 4 ? "orange" : "red";
+    const grade = score >= 9 ? "A+" : score >= 8 ? "A" : score >= 7 ? "B+" : score >= 6 ? "B" : score >= 5 ? "C" : score >= 3 ? "D" : "F";
+    console.log("");
+    console.log(`  \x1b[1mREADME Badge:\x1b[0m`);
+    console.log(`  ![Agent Security: ${grade}](https://img.shields.io/badge/Agent_Security-${grade}-${color})`);
+  }
+
+  process.exit(findings.score >= 6 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error("  \x1b[31mError:\x1b[0m", (err as Error).message);
+  process.exit(2);
+});

package/src/reporter.ts

@@ -0,0 +1,84 @@
+import type { ScanResult } from "./scanner.js";
+
+const COLORS = {
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  green: "\x1b[32m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+  white: "\x1b[37m",
+  bold: "\x1b[1m",
+  reset: "\x1b[0m",
+};
+
+const SEVERITY_LABEL: Record<string, string> = {
+  critical: `${COLORS.red}${COLORS.bold}CRITICAL${COLORS.reset}`,
+  warning: `${COLORS.yellow}WARNING ${COLORS.reset}`,
+  info: `${COLORS.cyan}INFO    ${COLORS.reset}`,
+  pass: `${COLORS.green}PASS    ${COLORS.reset}`,
+};
+
+function scoreBar(score: number): string {
+  const filled = Math.round(score * 2);
+  const empty = 20 - filled;
+  const color = score >= 8 ? COLORS.green : score >= 5 ? COLORS.yellow : COLORS.red;
+  return `${color}[${"=".repeat(filled)}${" ".repeat(empty)}]${COLORS.reset}`;
+}
+
+function gradeFromScore(score: number): string {
+  if (score >= 9) return `${COLORS.green}${COLORS.bold}A+${COLORS.reset}`;
+  if (score >= 8) return `${COLORS.green}${COLORS.bold}A${COLORS.reset}`;
+  if (score >= 7) return `${COLORS.green}B+${COLORS.reset}`;
+  if (score >= 6) return `${COLORS.yellow}B${COLORS.reset}`;
+  if (score >= 5) return `${COLORS.yellow}C${COLORS.reset}`;
+  if (score >= 3) return `${COLORS.red}D${COLORS.reset}`;
+  return `${COLORS.red}${COLORS.bold}F${COLORS.reset}`;
+}
+
+export function formatReport(result: ScanResult): string {
+  const lines: string[] = [];
+
+  // Summary
+  lines.push(`  ${COLORS.gray}Scanned ${result.scannedFiles} files${COLORS.reset}`);
+  lines.push(`  ${COLORS.gray}Found ${result.agents} agent(s), ${result.mcpServers} MCP server(s)${COLORS.reset}`);
+  lines.push("");
+
+  // Findings
+  if (result.findings.length === 0) {
+    lines.push(`  ${COLORS.green}${COLORS.bold}No issues found!${COLORS.reset}`);
+  } else {
+    for (const f of result.findings) {
+      const label = SEVERITY_LABEL[f.severity] ?? f.severity;
+      const file = f.file ? ` ${COLORS.gray}(${f.file})${COLORS.reset}` : "";
+      lines.push(`  ${label}  ${f.message}${file}`);
+      if (f.fix) {
+        lines.push(`           ${COLORS.gray}Fix: ${f.fix}${COLORS.reset}`);
+      }
+    }
+  }
+
+  lines.push("");
+
+  // Security posture
+  lines.push(`  ${COLORS.bold}Security Posture:${COLORS.reset}`);
+  lines.push(`    Identity layer:    ${result.hasIdentityLayer ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.red}No${COLORS.reset}`}`);
+  lines.push(`    Delegation chains: ${result.hasDelegation ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.red}No${COLORS.reset}`}`);
+  lines.push(`    Audit logging:     ${result.hasAuditLog ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.red}No${COLORS.reset}`}`);
+  lines.push(`    Approval workflows:${result.hasApprovals ? `${COLORS.green}Yes${COLORS.reset}` : `${COLORS.yellow} No${COLORS.reset}`}`);
+  lines.push("");
+
+  // Score
+  const criticals = result.findings.filter((f) => f.severity === "critical").length;
+  const warnings = result.findings.filter((f) => f.severity === "warning").length;
+
+  lines.push(`  ${COLORS.bold}Agent Security Score: ${result.score}/10${COLORS.reset}  ${scoreBar(result.score)}  Grade: ${gradeFromScore(result.score)}`);
+  lines.push(`  ${COLORS.gray}${criticals} critical, ${warnings} warnings${COLORS.reset}`);
+  lines.push("");
+
+  // CTAs
+  lines.push(`  ${COLORS.gray}Learn more:${COLORS.reset} https://github.com/authora-dev/awesome-agent-security`);
+  lines.push(`  ${COLORS.gray}Fix issues:${COLORS.reset} https://authora.dev/get-started`);
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/scanner.ts

@@ -0,0 +1,276 @@
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join, extname } from "path";
+
+export interface Finding {
+  severity: "critical" | "warning" | "info" | "pass";
+  category: string;
+  message: string;
+  file?: string;
+  line?: number;
+  fix?: string;
+}
+
+export interface ScanResult {
+  findings: Finding[];
+  score: number;
+  agents: number;
+  mcpServers: number;
+  hasIdentityLayer: boolean;
+  hasDelegation: boolean;
+  hasAuditLog: boolean;
+  hasApprovals: boolean;
+  scannedFiles: number;
+}
+
+const CODE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go", ".rs", ".java", ".rb",
+  ".json", ".yaml", ".yml", ".toml", ".env",
+]);
+
+const MAX_FILES = 500;
+const MAX_FILE_SIZE = 100_000; // 100KB
+
+function walkDir(dir: string, files: string[] = [], depth = 0): string[] {
+  if (depth > 8 || files.length > MAX_FILES) return files;
+
+  try {
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" ||
+          entry === "build" || entry === "__pycache__" || entry === "venv" ||
+          entry === ".git" || entry === "vendor") continue;
+
+      const fullPath = join(dir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          walkDir(fullPath, files, depth + 1);
+        } else if (stat.isFile() && CODE_EXTENSIONS.has(extname(entry)) && stat.size < MAX_FILE_SIZE) {
+          files.push(fullPath);
+        }
+      } catch {
+        // Skip inaccessible files
+      }
+    }
+  } catch {
+    // Skip inaccessible directories
+  }
+
+  return files;
+}
+
+function readFile(path: string): string {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export async function scanDirectory(dir: string): Promise<ScanResult> {
+  const findings: Finding[] = [];
+  let agents = 0;
+  let mcpServers = 0;
+  let hasIdentityLayer = false;
+  let hasDelegation = false;
+  let hasAuditLog = false;
+  let hasApprovals = false;
+
+  const files = walkDir(dir);
+
+  for (const file of files) {
+    const content = readFile(file);
+    if (!content) continue;
+    const lower = content.toLowerCase();
+    const relPath = file.replace(dir + "/", "");
+
+    // Detect agents
+    if (/\bagent\b/i.test(content) && (/\bcreate.*agent|agent.*config|new.*agent|agent.*class\b/i.test(content))) {
+      agents++;
+    }
+
+    // Detect MCP servers
+    if (/mcp.*server|mcpserver|model.*context.*protocol/i.test(lower)) {
+      mcpServers++;
+    }
+
+    // Check for identity layer
+    if (/authora|@authora\/sdk|agent.*identity|ed25519.*agent|agent.*keypair/i.test(lower)) {
+      hasIdentityLayer = true;
+    }
+
+    // Check for delegation
+    if (/delegation.*chain|delegate.*permission|token.*exchange|rfc.*8693/i.test(lower)) {
+      hasDelegation = true;
+    }
+
+    // Check for audit logging
+    if (/audit.*log|agent.*audit|action.*log.*agent/i.test(lower)) {
+      hasAuditLog = true;
+    }
+
+    // Check for approvals
+    if (/approval.*workflow|human.*in.*loop|require.*approval/i.test(lower)) {
+      hasApprovals = true;
+    }
+
+    // --- CRITICAL: Shared API keys ---
+    const apiKeyPattern = /(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|AZURE_API_KEY|API_KEY)\s*[=:]\s*["']?[A-Za-z0-9_-]{20,}/g;
+    const envFile = extname(file) === ".env";
+    if (envFile) {
+      const keys = content.match(apiKeyPattern);
+      if (keys && keys.length > 0) {
+        // Check if multiple agents might share this key
+        const agentFiles = files.filter((f) => {
+          const fc = readFile(f);
+          return /\bagent\b/i.test(fc) && /API_KEY|api_key|apiKey/i.test(fc);
+        });
+        if (agentFiles.length > 1) {
+          findings.push({
+            severity: "critical",
+            category: "credentials",
+            message: `Shared API key may be used by ${agentFiles.length} agent files`,
+            file: relPath,
+            fix: "Give each agent its own credentials with scoped permissions",
+          });
+        }
+      }
+    }
+
+    // --- CRITICAL: Hardcoded secrets in code ---
+    if (!envFile) {
+      const hardcodedSecrets = content.match(/(?:sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|xoxb-[0-9]+-[a-zA-Z0-9]+)/g);
+      if (hardcodedSecrets) {
+        findings.push({
+          severity: "critical",
+          category: "credentials",
+          message: `Hardcoded secret found in source code`,
+          file: relPath,
+          fix: "Move secrets to environment variables and use a secrets manager",
+        });
+      }
+    }
+
+    // --- WARNING: MCP server without auth ---
+    if (/mcp.*server|createServer/i.test(content) && !/auth|authentication|authorization|token|apiKey/i.test(content)) {
+      findings.push({
+        severity: "warning",
+        category: "mcp",
+        message: "MCP server detected without visible auth configuration",
+        file: relPath,
+        fix: "Add authentication to your MCP server (API key, JWT, or Ed25519 signature verification)",
+      });
+    }
+
+    // --- WARNING: Broad agent permissions ---
+    if (/\*.*permission|admin.*role|full.*access|sudo|root/i.test(content) && /agent/i.test(content)) {
+      findings.push({
+        severity: "warning",
+        category: "permissions",
+        message: "Agent may have overly broad permissions",
+        file: relPath,
+        fix: "Apply least-privilege: give agents only the permissions they need for their specific task",
+      });
+    }
+
+    // --- WARNING: No error handling on tool calls ---
+    if (/tool.*call|callTool|execute.*tool/i.test(content) && !/try|catch|error/i.test(content)) {
+      findings.push({
+        severity: "warning",
+        category: "resilience",
+        message: "Agent tool calls without error handling",
+        file: relPath,
+        fix: "Wrap tool calls in try/catch with proper error reporting and fallback behavior",
+      });
+    }
+
+    // --- INFO: Agent without timeout ---
+    if (/agent/i.test(content) && /async|await|fetch|request/i.test(content) && !/timeout|AbortSignal|signal/i.test(content)) {
+      findings.push({
+        severity: "info",
+        category: "resilience",
+        message: "Agent operations without timeout -- could run indefinitely",
+        file: relPath,
+        fix: "Add timeouts to agent operations to prevent runaway processes",
+      });
+    }
+  }
+
+  // --- Structural findings ---
+  if (!hasIdentityLayer) {
+    findings.push({
+      severity: "critical",
+      category: "identity",
+      message: "No agent identity layer detected",
+      fix: "Add cryptographic agent identities so each agent has a verifiable, unique identity. See: https://authora.dev/get-started",
+    });
+  }
+
+  if (!hasDelegation && agents > 1) {
+    findings.push({
+      severity: "warning",
+      category: "delegation",
+      message: "No delegation chains -- agents may inherit unlimited permissions",
+      fix: "Implement delegation chains (RFC 8693) so agents receive scoped, time-bound authority",
+    });
+  }
+
+  if (!hasAuditLog) {
+    findings.push({
+      severity: "warning",
+      category: "audit",
+      message: "No audit logging for agent actions detected",
+      fix: "Log every agent action with: who (agent ID), what (action), when (timestamp), authorized by (delegation chain)",
+    });
+  }
+
+  if (!hasApprovals && agents > 0) {
+    findings.push({
+      severity: "info",
+      category: "approvals",
+      message: "No approval workflows for sensitive agent actions",
+      fix: "Add human-in-the-loop approval for high-risk operations (production deploys, data access, secret rotation)",
+    });
+  }
+
+  if (mcpServers > 0 && !hasIdentityLayer) {
+    findings.push({
+      severity: "critical",
+      category: "mcp",
+      message: `${mcpServers} MCP server(s) found but no agent identity -- any client can call any tool`,
+      fix: "Add agent identity verification to your MCP servers. See: https://authora.dev/developers/mcp",
+    });
+  }
+
+  // Calculate score (0-10) based on CATEGORIES not raw count
+  // This prevents large codebases from being penalized for having many files
+  const criticalCategories = new Set(findings.filter((f) => f.severity === "critical").map((f) => f.category));
+  const warningCategories = new Set(findings.filter((f) => f.severity === "warning").map((f) => f.category));
+  const infoCategories = new Set(findings.filter((f) => f.severity === "info").map((f) => f.category));
+
+  let score = 10;
+  score -= criticalCategories.size * 2.5;
+  score -= warningCategories.size * 1.5;
+  score -= infoCategories.size * 0.5;
+
+  // Bonus for good practices (max +4)
+  if (hasIdentityLayer) score += 1;
+  if (hasDelegation) score += 1;
+  if (hasAuditLog) score += 1;
+  if (hasApprovals) score += 1;
+
+  score = Math.max(0, Math.min(10, Math.round(score * 10) / 10));
+
+  return {
+    findings,
+    score,
+    agents,
+    mcpServers,
+    hasIdentityLayer,
+    hasDelegation,
+    hasAuditLog,
+    hasApprovals,
+    scannedFiles: files.length,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}