@phenixstar/talon 1.0.0

package/bin/talon.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * Talon CLI — global entry point for `npx @phenixstar/talon` or `talon` (if installed globally).
+ * Routes to the appropriate TypeScript-compiled command in dist/cli/.
+ */
+
+import { execSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+
+const [,, command, ...args] = process.argv;
+
+const COMMANDS = {
+  setup:      'dist/cli/setup.js',
+  doctor:     'dist/cli/doctor.js',
+  help:       null,
+  start:      null,
+  stop:       null,
+  logs:       null,
+  workspaces: null,
+  benchmark:  null,
+  evolve:     null,
+};
+
+function showHelp() {
+  console.log(`
+Talon — AI Penetration Testing Framework
+
+Usage:
+  talon setup                          Interactive setup wizard
+  talon doctor                         Validate configuration and dependencies
+  talon start URL=<url> REPO=<name>   Start a pentest workflow
+  talon stop                          Stop all containers
+  talon stop CLEAN=true               Stop + remove volumes
+  talon workspaces                    List all workspaces
+  talon logs ID=<workflow-id>         Tail workflow logs
+  talon benchmark TARGET=<name>       Run benchmark metrics
+  talon evolve GENERATIONS=<n>        Run evolution generations
+  talon help                          Show this help
+
+Options for 'start':
+  REPO=<name>            Folder under ./repos/
+  CONFIG=<path>          YAML config file
+  OUTPUT=<path>          Output directory (default: ./audit-logs/)
+  WORKSPACE=<name>       Named workspace (auto-resume)
+  PIPELINE_TESTING=true  Fast testing mode
+  ROUTER=true            Multi-model routing
+
+Examples:
+  talon setup
+  talon start URL=https://example.com REPO=my-app
+  talon start URL=https://example.com REPO=my-app WORKSPACE=q1-audit
+`);
+}
+
+// 1. Handle help
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+// 2. Handle TypeScript CLI commands (setup, doctor)
+const cliScript = COMMANDS[command];
+if (cliScript) {
+  const scriptPath = resolve(root, cliScript);
+  if (!existsSync(scriptPath)) {
+    console.error(`Error: ${cliScript} not found. Run 'npm run build' first.`);
+    process.exit(1);
+  }
+  const child = spawn('node', [scriptPath, ...args], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else if (command in COMMANDS) {
+  // 3. Delegate Docker-based commands to the bash script
+  const talonSh = resolve(root, 'talon');
+  if (!existsSync(talonSh)) {
+    console.error('Error: talon bash script not found. Are you in the project directory?');
+    process.exit(1);
+  }
+  const child = spawn('bash', [talonSh, command, ...args], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else {
+  console.error(`Unknown command: ${command}`);
+  showHelp();
+  process.exit(1);
+}

package/bin/talon.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * Talon CLI — global entry point for `npx @phenixstar/talon` or `talon` (if installed globally).
+ * Routes to the appropriate TypeScript-compiled command in dist/cli/.
+ */
+
+import { execSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+
+const [,, command, ...args] = process.argv;
+
+const COMMANDS = {
+  setup:      'dist/cli/setup.js',
+  doctor:     'dist/cli/doctor.js',
+  help:       null,
+  start:      null,
+  stop:       null,
+  logs:       null,
+  workspaces: null,
+  benchmark:  null,
+  evolve:     null,
+};
+
+function showHelp() {
+  console.log(`
+Talon — AI Penetration Testing Framework
+
+Usage:
+  talon setup                          Interactive setup wizard
+  talon doctor                         Validate configuration and dependencies
+  talon start URL=<url> REPO=<name>   Start a pentest workflow
+  talon stop                          Stop all containers
+  talon stop CLEAN=true               Stop + remove volumes
+  talon workspaces                    List all workspaces
+  talon logs ID=<workflow-id>         Tail workflow logs
+  talon benchmark TARGET=<name>       Run benchmark metrics
+  talon evolve GENERATIONS=<n>        Run evolution generations
+  talon help                          Show this help
+
+Options for 'start':
+  REPO=<name>            Folder under ./repos/
+  CONFIG=<path>          YAML config file
+  OUTPUT=<path>          Output directory (default: ./audit-logs/)
+  WORKSPACE=<name>       Named workspace (auto-resume)
+  PIPELINE_TESTING=true  Fast testing mode
+  ROUTER=true            Multi-model routing
+
+Examples:
+  talon setup
+  talon start URL=https://example.com REPO=my-app
+  talon start URL=https://example.com REPO=my-app WORKSPACE=q1-audit
+`);
+}
+
+// 1. Handle help
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+// 2. Handle TypeScript CLI commands (setup, doctor)
+const cliScript = COMMANDS[command];
+if (cliScript) {
+  const scriptPath = resolve(root, cliScript);
+  if (!existsSync(scriptPath)) {
+    console.error(`Error: ${cliScript} not found. Run 'npm run build' first.`);
+    process.exit(1);
+  }
+  const child = spawn('node', [scriptPath, ...args], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else if (command in COMMANDS) {
+  // 3. Delegate Docker-based commands to the bash script
+  const talonSh = resolve(root, 'talon');
+  if (!existsSync(talonSh)) {
+    console.error('Error: talon bash script not found. Are you in the project directory?');
+    process.exit(1);
+  }
+  const child = spawn('bash', [talonSh, command, ...args], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else {
+  console.error(`Unknown command: ${command}`);
+  showHelp();
+  process.exit(1);
+}

package/configs/config-schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/pentest-config-schema.json",
+  "title": "Penetration Testing Configuration Schema",
+  "description": "Schema for YAML configuration files used in the penetration testing agent",
+  "type": "object",
+  "properties": {
+    "authentication": {
+      "type": "object",
+      "description": "Authentication configuration for the target application",
+      "properties": {
+        "login_type": {
+          "type": "string",
+          "enum": ["form", "sso", "api", "basic"],
+          "description": "Type of authentication mechanism"
+        },
+        "login_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL for the login page or endpoint"
+        },
+        "credentials": {
+          "type": "object",
+          "description": "Login credentials",
+          "properties": {
+            "username": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 255,
+              "description": "Username or email for authentication"
+            },
+            "password": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 255,
+              "description": "Password for authentication"
+            },
+            "totp_secret": {
+              "type": "string",
+              "pattern": "^[A-Za-z2-7]+=*$",
+              "description": "TOTP secret for two-factor authentication (Base32 encoded, case insensitive)"
+            }
+          },
+          "required": ["username", "password"],
+          "additionalProperties": false
+        },
+        "login_flow": {
+          "type": "array",
+          "description": "Step-by-step instructions for the login process",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500
+          },
+          "minItems": 1,
+          "maxItems": 20
+        },
+        "success_condition": {
+          "type": "object",
+          "description": "Condition that indicates successful authentication",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["url_contains", "element_present", "url_equals_exactly", "text_contains"],
+              "description": "Type of success condition to check"
+            },
+            "value": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 500,
+              "description": "Value to match against the success condition"
+            }
+          },
+          "required": ["type", "value"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["login_type", "login_url", "credentials", "success_condition"],
+      "additionalProperties": false
+    },
+    "pipeline": {
+      "type": "object",
+      "description": "Pipeline execution settings for retry behavior and concurrency",
+      "properties": {
+        "retry_preset": {
+          "type": "string",
+          "enum": ["default", "subscription"],
+          "description": "Retry preset. 'subscription' extends timeouts for Anthropic subscription rate limit windows (5h+)."
+        },
+        "max_concurrent_pipelines": {
+          "type": "string",
+          "pattern": "^[1-5]$",
+          "description": "Max concurrent vulnerability pipelines (1-5, default: 5)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "rules": {
+      "type": "object",
+      "description": "Testing rules that define what to focus on or avoid during penetration testing",
+      "properties": {
+        "avoid": {
+          "type": "array",
+          "description": "Rules defining areas to avoid during testing",
+          "items": {
+            "$ref": "#/$defs/rule"
+          },
+          "maxItems": 50
+        },
+        "focus": {
+          "type": "array",
+          "description": "Rules defining areas to focus on during testing",
+          "items": {
+            "$ref": "#/$defs/rule"
+          },
+          "maxItems": 50
+        }
+      },
+      "additionalProperties": false
+    },
+    "login": {
+      "type": "object",
+      "description": "Deprecated: Use 'authentication' section instead",
+      "deprecated": true
+    }
+  },
+  "anyOf": [
+    {"required": ["authentication"]},
+    {"required": ["rules"]},
+    {"required": ["authentication", "rules"]}
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "rule": {
+      "type": "object",
+      "description": "A single testing rule",
+      "properties": {
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable description of the rule"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["path", "subdomain", "domain", "method", "header", "parameter"],
+          "description": "Type of rule (what aspect of requests to match against)"
+        },
+        "url_path": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "description": "URL path pattern or value to match"
+        }
+      },
+      "required": ["description", "type", "url_path"],
+      "additionalProperties": false
+    }
+  }
+}

package/configs/example-config.yaml

@@ -0,0 +1,50 @@
+# Example configuration file for pentest-agent
+# Copy this file and modify it for your specific testing needs
+
+authentication:
+  login_type: form  # Options: 'form' or 'sso'
+  login_url: "https://example.com/login"
+  credentials:
+    username: "testuser"
+    password: "testpassword"
+    totp_secret: "JBSWY3DPEHPK3PXP"  # Optional TOTP secret for 2FA
+  
+  # Natural language instructions for login flow
+  login_flow:
+    - "Type $username into the email field"
+    - "Type $password into the password field"
+    - "Click the 'Sign In' button"
+    - "Enter $totp in the verification code field"
+    - "Click 'Verify'"
+  
+  success_condition:
+    type: url_contains  # Options: 'url_contains' or 'element_present'
+    value: "/dashboard"
+
+rules:
+  avoid:
+    - description: "Do not test the marketing site subdomain"
+      type: subdomain
+      url_path: "www"
+    
+    - description: "Skip logout functionality"
+      type: path
+      url_path: "/logout"
+    
+    - description: "No DELETE operations on user API"
+      type: path
+      url_path: "/api/v1/users/*"
+  
+  focus:
+    - description: "Prioritize beta admin panel subdomain"
+      type: subdomain
+      url_path: "beta-admin"
+
+    - description: "Focus on user profile updates"
+      type: path
+      url_path: "/api/v2/user-profile"
+
+# Pipeline execution settings (optional)
+# pipeline:
+#   retry_preset: subscription          # 'default' or 'subscription' (6h max retry for rate limit recovery)
+#   max_concurrent_pipelines: 2         # 1-5, default: 5 (reduce to lower API usage spikes)

package/configs/mcp-allowlist.json

@@ -0,0 +1,47 @@
+{
+  "modes": {
+    "reconnaissance": {
+      "allowed": [
+        "nmap", "subfinder", "whatweb", "httpx",
+        "browser_navigate", "browser_snapshot", "browser_click",
+        "browser_type", "browser_wait_for", "browser_take_screenshot",
+        "save_deliverable", "list_deliverables"
+      ]
+    },
+    "exploitation": {
+      "allowed": [
+        "browser_navigate", "browser_snapshot", "browser_click",
+        "browser_type", "browser_fill_form", "browser_wait_for",
+        "browser_take_screenshot", "browser_evaluate",
+        "save_deliverable", "list_deliverables",
+        "generate_totp"
+      ]
+    },
+    "reporting": {
+      "allowed": [
+        "save_deliverable", "list_deliverables",
+        "browser_take_screenshot"
+      ]
+    },
+    "all": {
+      "allowed": [
+        "nmap", "subfinder", "whatweb", "httpx",
+        "browser_navigate", "browser_snapshot", "browser_click",
+        "browser_type", "browser_fill_form", "browser_wait_for",
+        "browser_take_screenshot", "browser_evaluate",
+        "save_deliverable", "list_deliverables",
+        "generate_totp"
+      ]
+    }
+  },
+  "denied": [
+    "exec", "shell", "python_eval", "eval",
+    "bash", "sh", "cmd", "powershell"
+  ],
+  "rateLimits": {
+    "nmap": { "maxPerMinute": 2 },
+    "browser_navigate": { "maxPerMinute": 30 },
+    "browser_evaluate": { "maxPerMinute": 10 },
+    "save_deliverable": { "maxPerMinute": 20 }
+  }
+}

package/configs/model-routing.yaml

@@ -0,0 +1,39 @@
+# Model routing configuration for multi-LLM orchestration.
+# Each pipeline phase routes to the optimal model based on task requirements.
+#
+# Format: primary model attempted first; fallback used on provider failure.
+# Model IDs must match provider catalog in router-config.json.
+
+routes:
+  # Pre-recon: code analysis needs deep reasoning
+  pre-recon:
+    primary: claude-opus-4-6
+    fallback: claude-sonnet-4-6
+
+  # Recon: tool-heavy scanning, moderate reasoning
+  recon:
+    primary: claude-sonnet-4-6
+    fallback: claude-haiku-4-5-20251001
+
+  # Vulnerability analysis: deep reasoning for complex vuln patterns
+  vulnerability-analysis:
+    primary: claude-sonnet-4-6
+    fallback: claude-haiku-4-5-20251001
+
+  # Exploitation: highest capability needed for exploit generation
+  exploitation:
+    primary: claude-opus-4-6
+    fallback: claude-sonnet-4-6
+
+  # Reporting: structured extraction, moderate reasoning
+  reporting:
+    primary: claude-sonnet-4-6
+    fallback: claude-haiku-4-5-20251001
+
+# Budget guard: halt execution if cumulative cost exceeds this threshold (USD)
+spending_cap_per_run: 10.00
+
+# Circuit breaker settings
+circuit_breaker:
+  failure_threshold: 3        # consecutive failures before marking unhealthy
+  recovery_timeout_ms: 30000  # ms before retrying unhealthy provider

package/configs/router-config.json

@@ -0,0 +1,73 @@
+{
+  "HOST": "0.0.0.0",
+  "APIKEY": "$TALON_ROUTER_KEY",
+  "LOG": true,
+  "LOG_LEVEL": "info",
+  "NON_INTERACTIVE_MODE": true,
+  "API_TIMEOUT_MS": 3000000,
+  "Providers": [
+    {
+      "name": "openrouter",
+      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
+      "api_key": "$OPENROUTER_API_KEY",
+      "models": [
+        "anthropic/claude-opus-4-6",
+        "anthropic/claude-sonnet-4-6",
+        "anthropic/claude-haiku-4-5-20251001",
+        "google/gemini-3-flash-preview",
+        "meta-llama/llama-4-maverick"
+      ],
+      "transformer": {
+        "use": ["openrouter"]
+      }
+    },
+    {
+      "name": "groq",
+      "api_base_url": "https://api.groq.com/openai/v1/chat/completions",
+      "api_key": "$GROQ_API_KEY",
+      "models": ["llama-3.3-70b-versatile", "mixtral-8x7b-32768"],
+      "transformer": {
+        "use": [["maxcompletiontokens", { "max_completion_tokens": 32768 }]]
+      }
+    },
+    {
+      "name": "xai",
+      "api_base_url": "https://api.x.ai/v1/chat/completions",
+      "api_key": "$XAI_API_KEY",
+      "models": ["grok-3", "grok-3-mini"],
+      "transformer": {
+        "use": [["maxcompletiontokens", { "max_completion_tokens": 32768 }]]
+      }
+    },
+    {
+      "name": "kimi",
+      "api_base_url": "https://api.moonshot.cn/v1/chat/completions",
+      "api_key": "$KIMI_API_KEY",
+      "models": ["moonshot-v1-128k"],
+      "transformer": {
+        "use": [["maxcompletiontokens", { "max_completion_tokens": 16384 }]]
+      }
+    },
+    {
+      "name": "minimax",
+      "api_base_url": "https://api.minimax.io/v1/chat/completions",
+      "api_key": "$MINIMAX_HIGHSPEED_API_KEY",
+      "models": ["MiniMax-M2.5-highspeed", "MiniMax-M2.5"],
+      "transformer": {
+        "use": [["maxcompletiontokens", { "max_completion_tokens": 16384 }]]
+      }
+    },
+    {
+      "name": "z-ai",
+      "api_base_url": "https://api.z.ai/api/coding/paas/v4/chat/completions",
+      "api_key": "$ZAI_CODING_PLAN_API_KEY",
+      "models": ["GLM-4.7", "GLM-4.5-Air"],
+      "transformer": {
+        "use": [["maxcompletiontokens", { "max_completion_tokens": 16384 }]]
+      }
+    }
+  ],
+  "Router": {
+    "default": "$ROUTER_DEFAULT"
+  }
+}

package/configs/talon-seccomp.json

@@ -0,0 +1,89 @@
+{
+  "defaultAction": "SCMP_ACT_ERRNO",
+  "defaultErrnoRet": 1,
+  "archMap": [
+    {
+      "architecture": "SCMP_ARCH_X86_64",
+      "subArchitectures": ["SCMP_ARCH_X86", "SCMP_ARCH_X32"]
+    }
+  ],
+  "syscalls": [
+    {
+      "names": [
+        "accept", "accept4", "access", "arch_prctl", "bind", "brk",
+        "capget", "capset", "chdir", "clock_getres", "clock_gettime",
+        "clock_nanosleep", "clone", "clone3", "close", "close_range",
+        "connect", "copy_file_range",
+        "dup", "dup2", "dup3",
+        "epoll_create1", "epoll_ctl", "epoll_pwait", "epoll_pwait2", "epoll_wait",
+        "eventfd2", "execve", "execveat", "exit", "exit_group",
+        "faccessat", "faccessat2", "fadvise64", "fallocate",
+        "fcntl", "flock", "fork", "fstat", "fstatfs", "fsync",
+        "ftruncate", "futex", "futex_waitv",
+        "getcwd", "getdents64", "getegid", "geteuid", "getgid",
+        "getgroups", "getpeername", "getpgid", "getpgrp", "getpid",
+        "getppid", "getpriority", "getrandom", "getresgid", "getresuid",
+        "getrlimit", "getrusage", "getsid", "getsockname", "getsockopt",
+        "gettid", "gettimeofday", "getuid", "getxattr",
+        "inotify_add_watch", "inotify_init1", "inotify_rm_watch",
+        "ioctl", "io_uring_enter", "io_uring_register", "io_uring_setup",
+        "kill",
+        "lgetxattr", "link", "linkat", "listen", "lseek", "lstat",
+        "madvise", "membarrier", "memfd_create", "mincore",
+        "mkdir", "mkdirat", "mlock", "mlock2", "mlockall",
+        "mmap", "mprotect", "mremap", "msync", "munlock", "munlockall", "munmap",
+        "name_to_handle_at", "nanosleep", "newfstatat",
+        "open", "openat", "openat2",
+        "pause", "pipe", "pipe2", "poll", "ppoll",
+        "prctl", "pread64", "preadv", "preadv2", "prlimit64",
+        "pselect6", "pwrite64", "pwritev", "pwritev2",
+        "read", "readahead", "readlink", "readlinkat", "readv",
+        "recvfrom", "recvmmsg", "recvmsg",
+        "remap_file_pages", "renameat", "renameat2",
+        "restart_syscall", "rmdir",
+        "rseq",
+        "rt_sigaction", "rt_sigpending", "rt_sigprocmask",
+        "rt_sigqueueinfo", "rt_sigreturn", "rt_sigsuspend",
+        "rt_sigtimedwait",
+        "sched_getaffinity", "sched_getattr", "sched_getparam",
+        "sched_get_priority_max", "sched_get_priority_min",
+        "sched_getscheduler", "sched_setaffinity", "sched_yield",
+        "seccomp",
+        "select", "sendfile", "sendmmsg", "sendmsg", "sendto",
+        "set_robust_list", "set_tid_address",
+        "setfsgid", "setfsuid", "setgid", "setgroups",
+        "setitimer", "setpgid", "setpriority",
+        "setregid", "setresgid", "setresuid", "setreuid",
+        "setrlimit", "setsid", "setsockopt", "settimeofday",
+        "setuid",
+        "shutdown",
+        "sigaltstack",
+        "signalfd4",
+        "socket", "socketpair", "splice",
+        "stat", "statfs", "statx",
+        "symlink", "symlinkat",
+        "sync", "sync_file_range", "syncfs",
+        "sysinfo",
+        "tgkill", "timerfd_create", "timerfd_gettime", "timerfd_settime",
+        "times", "tkill",
+        "truncate",
+        "umask", "uname", "unlink", "unlinkat", "unshare",
+        "utime", "utimensat",
+        "vfork",
+        "wait4", "waitid",
+        "write", "writev"
+      ],
+      "action": "SCMP_ACT_ALLOW"
+    },
+    {
+      "comment": "Log but allow ptrace for Chromium sandbox",
+      "names": ["ptrace"],
+      "action": "SCMP_ACT_LOG"
+    },
+    {
+      "comment": "Log but allow process_vm ops for Chromium debugging",
+      "names": ["process_vm_readv", "process_vm_writev"],
+      "action": "SCMP_ACT_LOG"
+    }
+  ]
+}

package/dist/cli/dependency-checker.d.ts

@@ -0,0 +1,25 @@
+export interface DependencyStatus {
+    name: string;
+    required: boolean;
+    installed: boolean;
+    version: string | null;
+    minVersion: string | null;
+    versionOk: boolean;
+    installHint: string;
+}
+export type RunMode = 'docker' | 'bare-metal';
+/** Parse a version string like "v22.11.0" or "Docker version 27.5.1, build abc" into semver parts */
+export declare function parseVersion(raw: string): string | null;
+/** Compare two semver strings: returns true if actual >= required */
+export declare function versionSatisfies(actual: string, required: string): boolean;
+/** Check if Docker daemon is running (not just installed) */
+export declare function isDockerRunning(): boolean;
+/** Check available disk space in GB */
+export declare function checkDiskSpaceGb(): number | null;
+/** Run all dependency checks for the given run mode */
+export declare function checkAllDependencies(mode: RunMode): DependencyStatus[];
+/** Detect recommended run mode based on available tools */
+export declare function detectRunMode(): RunMode;
+/** Check if repos directory exists */
+export declare function hasReposDir(): boolean;
+//# sourceMappingURL=dependency-checker.d.ts.map