@musashimiyamoto/agent-guard 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# 🛡 Agent Guard
+
+Security scanner for AI agent configurations. Detects misconfigurations, exposed secrets, and unsafe skill patterns.
+
+## Quick Start
+
+```bash
+# Scan current directory
+npx agent-guard scan .
+
+# Scan specific agent
+npx agent-guard scan ./my-agent
+
+# JSON output for CI/CD
+npx agent-guard scan . --json
+```
+
+## What It Finds
+
+| Category | Examples |
+|----------|----------|
+| **Secrets** | OpenAI keys, GitHub tokens, AWS credentials, private keys |
+| **Network** | Public binds (0.0.0.0), CORS misconfig, exfiltration URLs |
+| **Auth** | Missing authentication, default credentials |
+| **Skills** | Missing manifests, shell execution, eval usage |
+| **Injection** | Hidden unicode characters (RTL attacks) |
+
+## Security Score
+
+```
+Score: 90/100 (A)
+██████████████████░░
+
+Critical: 0
+High: 1
+Medium: 0
+Low: 0
+```
+
+- **A (90-100)**: Production ready
+- **B (80-89)**: Minor issues
+- **C (70-79)**: Needs attention
+- **D (60-69)**: Significant issues
+- **F (<60)**: Critical vulnerabilities
+
+## Skill Manifests
+
+Every skill should include `skill.manifest.json`:
+
+```json
+{
+  "metadata": {
+    "name": "my-skill",
+    "version": "1.0.0",
+    "author": "agent:id",
+    "isnad_root": "human:owner"
+  },
+  "permissions": {
+    "network": {
+      "egress": [{"domain": "api.example.com", "purpose": "core"}],
+      "block_all_other": true
+    },
+    "filesystem": {
+      "read": ["./data/"],
+      "write": ["./output/"],
+      "deny": ["~/.env", "~/.ssh"]
+    }
+  },
+  "runtime_policy": {
+    "enforcement": "hard_block",
+    "log_violations": true
+  }
+}
+```
+
+## Trust Tiers (Isnād)
+
+| Tier | Name | Meaning |
+|------|------|---------|
+| 🥇 | Thiqah | Audited by 3+ trusted agents, signed |
+| 🥈 | Hasan | Reputable author, signed manifest |
+| 🥉 | Da'if | Unsigned/unaudited, sandbox required |
+| 💀 | Matruk | Confirmed malicious, blocked |
+
+## Exit Codes
+
+- `0` — No critical findings
+- `1` — Critical findings detected
+- `2` — Scan error
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@musashimiyamoto/agent-guard",
+  "version": "0.1.0",
+  "description": "Security scanner for AI agent configurations. Detects misconfigurations, exposed secrets, and unsafe skill patterns.",
+  "main": "src/index.js",
+  "bin": {
+    "agent-guard": "./src/cli.js"
+  },
+  "scripts": {
+    "scan": "node src/cli.js scan",
+    "test": "node src/cli.js scan test/fixtures/vulnerable-agent --json"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "security",
+    "scanner",
+    "openclaw",
+    "moltbook",
+    "llm",
+    "vulnerability",
+    "secrets",
+    "audit"
+  ],
+  "author": "Agent Guard <security@agentguard.dev>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentguard/agent-guard"
+  },
+  "homepage": "https://agentguard.dev",
+  "bugs": {
+    "url": "https://github.com/agentguard/agent-guard/issues"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "yaml": "^2.3.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+// Agent Guard CLI
+// Security scanner for AI agent configurations
+
+import { scan } from './scanner.js';
+import { resolve } from 'path';
+
+import { createProxy } from './proxy/index.js';
+
+const VERSION = '0.1.0';
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m'
+};
+
+const SEVERITY_COLORS = {
+  critical: COLORS.red,
+  high: COLORS.magenta,
+  medium: COLORS.yellow,
+  low: COLORS.cyan
+};
+
+const SEVERITY_ICONS = {
+  critical: '🚨',
+  high: '⚠️ ',
+  medium: '📋',
+  low: 'ℹ️ '
+};
+
+function printBanner() {
+  console.log(`
+${COLORS.cyan}╔═══════════════════════════════════════════════════╗
+║                                                   ║
+║   ${COLORS.bold}🛡  AGENT GUARD${COLORS.reset}${COLORS.cyan}  v${VERSION}                       ║
+║   Security Scanner for AI Agents                  ║
+║                                                   ║
+╚═══════════════════════════════════════════════════╝${COLORS.reset}
+`);
+}
+
+function printHelp() {
+  console.log(`
+${COLORS.bold}Usage:${COLORS.reset}
+  agent-guard scan [path]     Scan directory for security issues
+  agent-guard proxy [port]    Start runtime protection proxy
+  agent-guard --help          Show this help message
+  agent-guard --version       Show version
+
+${COLORS.bold}Examples:${COLORS.reset}
+  npx agent-guard scan .              Scan current directory
+  npx agent-guard scan ./my-agent     Scan specific agent directory
+  npx agent-guard proxy               Start proxy on port 18800
+  npx agent-guard proxy 8080          Start proxy on custom port
+
+${COLORS.bold}Options:${COLORS.reset}
+  --json                      Output results as JSON
+  --quiet                     Only show findings (no banner)
+  --policy <file>             Use custom policy file
+
+${COLORS.bold}Environment:${COLORS.reset}
+  HTTP_PROXY=http://127.0.0.1:18800   Route agent through proxy
+
+${COLORS.bold}Exit Codes:${COLORS.reset}
+  0    No critical findings
+  1    Critical findings detected
+  2    Error during scan
+`);
+}
+
+function printScore(report) {
+  const { score, grade } = report;
+  
+  const gradeColor = 
+    grade === 'A' ? COLORS.green :
+    grade === 'B' ? COLORS.cyan :
+    grade === 'C' ? COLORS.yellow :
+    grade === 'D' ? COLORS.magenta : COLORS.red;
+  
+  const bar = '█'.repeat(Math.floor(score / 5)) + '░'.repeat(20 - Math.floor(score / 5));
+  
+  console.log(`
+${COLORS.bold}Security Score:${COLORS.reset} ${gradeColor}${score}/100 (${grade})${COLORS.reset}
+
+  ${gradeColor}${bar}${COLORS.reset}
+
+${COLORS.bold}Summary:${COLORS.reset}
+  ${COLORS.red}Critical:${COLORS.reset} ${report.summary.critical}
+  ${COLORS.magenta}High:${COLORS.reset}     ${report.summary.high}
+  ${COLORS.yellow}Medium:${COLORS.reset}   ${report.summary.medium}
+  ${COLORS.cyan}Low:${COLORS.reset}      ${report.summary.low}
+
+  Files scanned: ${report.scannedFiles}
+`);
+}
+
+function printFindings(findings) {
+  if (findings.length === 0) {
+    console.log(`${COLORS.green}✓ No security issues found!${COLORS.reset}\n`);
+    return;
+  }
+  
+  console.log(`${COLORS.bold}Findings:${COLORS.reset}\n`);
+  
+  // Group by severity
+  const grouped = {
+    critical: findings.filter(f => f.severity === 'critical'),
+    high: findings.filter(f => f.severity === 'high'),
+    medium: findings.filter(f => f.severity === 'medium'),
+    low: findings.filter(f => f.severity === 'low')
+  };
+  
+  for (const severity of ['critical', 'high', 'medium', 'low']) {
+    const items = grouped[severity];
+    if (items.length === 0) continue;
+    
+    const color = SEVERITY_COLORS[severity];
+    const icon = SEVERITY_ICONS[severity];
+    
+    console.log(`${color}${COLORS.bold}${icon} ${severity.toUpperCase()} (${items.length})${COLORS.reset}\n`);
+    
+    for (const finding of items) {
+      const lineInfo = finding.line ? `:${finding.line}` : '';
+      console.log(`  ${color}[${finding.rule}]${COLORS.reset} ${finding.name}`);
+      console.log(`  ${COLORS.gray}${finding.file}${lineInfo}${COLORS.reset}`);
+      console.log(`  ${finding.description}`);
+      console.log(`  Match: ${COLORS.yellow}${finding.match}${COLORS.reset}`);
+      console.log();
+    }
+  }
+}
+
+function printRecommendations(report) {
+  if (report.totalFindings === 0) return;
+  
+  console.log(`${COLORS.bold}Recommendations:${COLORS.reset}\n`);
+  
+  const hasSecrets = report.findings.some(f => f.rule.startsWith('SEC-'));
+  const hasNetwork = report.findings.some(f => f.rule.startsWith('NET-'));
+  const hasAuth = report.findings.some(f => f.rule.startsWith('AUTH-'));
+  const hasSkill = report.findings.some(f => f.rule.startsWith('SKILL-'));
+  
+  if (hasSecrets) {
+    console.log(`  ${COLORS.red}1.${COLORS.reset} Rotate exposed API keys immediately`);
+    console.log(`     Move secrets to environment variables or a vault\n`);
+  }
+  
+  if (hasNetwork) {
+    console.log(`  ${COLORS.red}2.${COLORS.reset} Fix network exposure`);
+    console.log(`     Bind to 127.0.0.1 instead of 0.0.0.0`);
+    console.log(`     Use a reverse proxy with authentication\n`);
+  }
+  
+  if (hasAuth) {
+    console.log(`  ${COLORS.red}3.${COLORS.reset} Enable authentication`);
+    console.log(`     Configure JWT or API key authentication\n`);
+  }
+  
+  if (hasSkill) {
+    console.log(`  ${COLORS.yellow}4.${COLORS.reset} Review skill permissions`);
+    console.log(`     Add skill.manifest.json with explicit permissions`);
+    console.log(`     Audit skills using shell execution\n`);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  const jsonOutput = args.includes('--json');
+  const quiet = args.includes('--quiet');
+  const filteredArgs = args.filter(a => !a.startsWith('--'));
+  
+  if (args.includes('--help') || args.includes('-h')) {
+    printBanner();
+    printHelp();
+    process.exit(0);
+  }
+  
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(`agent-guard v${VERSION}`);
+    process.exit(0);
+  }
+  
+  const command = filteredArgs[0];
+  
+  if (command === 'proxy') {
+    const port = parseInt(filteredArgs[1]) || 18800;
+    if (!quiet) printBanner();
+    console.log(`${COLORS.cyan}Starting runtime protection proxy...${COLORS.reset}\n`);
+    
+    try {
+      const proxy = createProxy({ port });
+      proxy.start();
+      
+      console.log(`${COLORS.green}Proxy ready.${COLORS.reset}`);
+      console.log(`${COLORS.gray}Set HTTP_PROXY=http://127.0.0.1:${port} to route agent traffic${COLORS.reset}\n`);
+      
+      // Keep running
+      process.on('SIGINT', () => {
+        console.log(`\n${COLORS.yellow}Shutting down...${COLORS.reset}`);
+        proxy.stop();
+        process.exit(0);
+      });
+    } catch (err) {
+      console.error(`${COLORS.red}Error: ${err.message}${COLORS.reset}`);
+      process.exit(2);
+    }
+    return;
+  }
+  
+  if (command !== 'scan') {
+    if (!quiet) printBanner();
+    printHelp();
+    process.exit(0);
+  }
+  
+  const targetPath = resolve(filteredArgs[1] || '.');
+  
+  if (!quiet && !jsonOutput) {
+    printBanner();
+    console.log(`${COLORS.gray}Scanning: ${targetPath}${COLORS.reset}\n`);
+  }
+  
+  try {
+    const report = await scan(targetPath);
+    
+    if (jsonOutput) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      printScore(report);
+      printFindings(report.findings);
+      printRecommendations(report);
+    }
+    
+    // Exit with 1 if critical findings
+    process.exit(report.summary.critical > 0 ? 1 : 0);
+    
+  } catch (err) {
+    console.error(`${COLORS.red}Error: ${err.message}${COLORS.reset}`);
+    process.exit(2);
+  }
+}
+
+main();

package/src/proxy/egress.js

@@ -0,0 +1,112 @@
+// Egress Control Module
+// Checks if outbound requests are allowed by policy
+
+// Known malicious/exfiltration domains
+const BLOCKED_DOMAINS = [
+  'webhook.site',
+  'requestbin.com',
+  'ngrok.io',
+  'pipedream.net',
+  'hookbin.com',
+  'burpcollaborator.net',
+  'oastify.com',
+  'interact.sh'
+];
+
+// Default allowed domains (LLM APIs)
+const DEFAULT_ALLOWED = [
+  'api.openai.com',
+  'api.anthropic.com',
+  'generativelanguage.googleapis.com',
+  'api.mistral.ai',
+  'api.cohere.ai',
+  'api.together.xyz',
+  'openrouter.ai'
+];
+
+export function checkEgress(url, policy = {}) {
+  const hostname = url.hostname.toLowerCase();
+  
+  // Check blocked domains first (always blocked)
+  for (const blocked of BLOCKED_DOMAINS) {
+    if (hostname === blocked || hostname.endsWith('.' + blocked)) {
+      return {
+        allowed: false,
+        reason: `Domain "${blocked}" is on the blocklist (known exfiltration endpoint)`
+      };
+    }
+  }
+
+  // Check policy-specific blocks
+  if (policy.egress?.rules) {
+    for (const rule of policy.egress.rules) {
+      if (matchDomain(hostname, rule.domain || rule.pattern)) {
+        if (rule.allow === false) {
+          return {
+            allowed: false,
+            reason: rule.reason || `Blocked by policy rule: ${rule.pattern || rule.domain}`
+          };
+        }
+        if (rule.allow === true) {
+          return {
+            allowed: true,
+            reason: rule.purpose || 'Allowed by policy'
+          };
+        }
+      }
+    }
+  }
+
+  // Check default allowed
+  for (const allowed of DEFAULT_ALLOWED) {
+    if (hostname === allowed || hostname.endsWith('.' + allowed)) {
+      return {
+        allowed: true,
+        reason: 'Default allowed (LLM API)'
+      };
+    }
+  }
+
+  // Check policy default action
+  const defaultAction = policy.egress?.default || 'deny';
+  
+  if (defaultAction === 'allow') {
+    return {
+      allowed: true,
+      reason: 'Allowed by default policy'
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: 'Not in allowlist (default deny)'
+  };
+}
+
+function matchDomain(hostname, pattern) {
+  if (!pattern) return false;
+  
+  // Exact match
+  if (hostname === pattern) return true;
+  
+  // Wildcard match (*.example.com)
+  if (pattern.startsWith('*.')) {
+    const suffix = pattern.slice(2);
+    return hostname === suffix || hostname.endsWith('.' + suffix);
+  }
+  
+  // Subdomain match (matches example.com and *.example.com)
+  return hostname.endsWith('.' + pattern);
+}
+
+export function addToBlocklist(domain) {
+  if (!BLOCKED_DOMAINS.includes(domain)) {
+    BLOCKED_DOMAINS.push(domain);
+  }
+}
+
+export function addToAllowlist(domain) {
+  if (!DEFAULT_ALLOWED.includes(domain)) {
+    DEFAULT_ALLOWED.push(domain);
+  }
+}

package/src/proxy/index.js

@@ -0,0 +1,132 @@
+// Agent Guard Runtime Proxy
+// Phase 2: Inference-level protection
+
+import { createServer } from 'http';
+import { request as httpRequest } from 'http';
+import { request as httpsRequest } from 'https';
+import { URL } from 'url';
+import { loadPolicy } from './policy.js';
+import { checkEgress } from './egress.js';
+import { logEvent } from './logger.js';
+
+const DEFAULT_PORT = 18800;
+
+export class AgentGuardProxy {
+  constructor(options = {}) {
+    this.port = options.port || DEFAULT_PORT;
+    this.policy = options.policy || loadPolicy();
+    this.server = null;
+  }
+
+  start() {
+    this.server = createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    this.server.listen(this.port, '127.0.0.1', () => {
+      console.log(`🛡 Agent Guard Proxy listening on http://127.0.0.1:${this.port}`);
+    });
+
+    return this;
+  }
+
+  stop() {
+    if (this.server) {
+      this.server.close();
+    }
+  }
+
+  async handleRequest(clientReq, clientRes) {
+    const startTime = Date.now();
+    
+    try {
+      // Parse target URL from proxy request
+      const targetUrl = new URL(clientReq.url);
+      
+      // Check egress policy
+      const egressResult = checkEgress(targetUrl, this.policy);
+      
+      if (!egressResult.allowed) {
+        logEvent({
+          type: 'egress_blocked',
+          target: targetUrl.hostname,
+          reason: egressResult.reason,
+          violation: true
+        });
+
+        clientRes.writeHead(403, { 'Content-Type': 'application/json' });
+        clientRes.end(JSON.stringify({
+          error: 'EGRESS_DENIED',
+          message: `Access to ${targetUrl.hostname} blocked by security policy`,
+          reason: egressResult.reason
+        }));
+        return;
+      }
+
+      logEvent({
+        type: 'egress_allowed',
+        target: targetUrl.hostname,
+        violation: false
+      });
+
+      // Forward request to target
+      const response = await this.forwardRequest(clientReq, targetUrl);
+      
+      // Log response (for intent verification later)
+      const latency = Date.now() - startTime;
+      logEvent({
+        type: 'request_complete',
+        target: targetUrl.hostname,
+        status: response.statusCode,
+        latency
+      });
+
+      // Forward response to client
+      clientRes.writeHead(response.statusCode, response.headers);
+      response.pipe(clientRes);
+
+    } catch (err) {
+      logEvent({
+        type: 'proxy_error',
+        error: err.message,
+        violation: false
+      });
+
+      clientRes.writeHead(502, { 'Content-Type': 'application/json' });
+      clientRes.end(JSON.stringify({
+        error: 'PROXY_ERROR',
+        message: err.message
+      }));
+    }
+  }
+
+  forwardRequest(clientReq, targetUrl) {
+    return new Promise((resolve, reject) => {
+      const requestFn = targetUrl.protocol === 'https:' ? httpsRequest : httpRequest;
+      
+      const options = {
+        hostname: targetUrl.hostname,
+        port: targetUrl.port || (targetUrl.protocol === 'https:' ? 443 : 80),
+        path: targetUrl.pathname + targetUrl.search,
+        method: clientReq.method,
+        headers: {
+          ...clientReq.headers,
+          host: targetUrl.host
+        }
+      };
+
+      const proxyReq = requestFn(options, (proxyRes) => {
+        resolve(proxyRes);
+      });
+
+      proxyReq.on('error', reject);
+
+      // Forward request body
+      clientReq.pipe(proxyReq);
+    });
+  }
+}
+
+export function createProxy(options) {
+  return new AgentGuardProxy(options);
+}