toolbox AGENTS.md

Project Overview

go-appsec/toolbox (sectool) is a CLI and MCP toolkit for human and LLM agent collaboration for application security testing.

Key characteristics:

• MCP-primary architecture: single API serves both agents and CLI
• CLI is a thin client over MCP for human interaction
• Global config at ~/.sectool/config.json (auto-created)
• All output in markdown format for LLM consumption
• Pluggable backend architecture (native built-in proxy or Burp MCP for HTTP, Interactsh for OAST, Colly for crawling)

Build Commands

make build          # Build to bin/sectool
make build-cross    # Cross-compile (linux/darwin, amd64/arm64)
make test           # Quick tests (-short flag)
make test-all       # Full tests with -race and coverage
make lint           # Run golangci-lint and go vet

Architecture

CLI Command → MCP Client → MCP Server → Backends (Built-in Proxy or Burp MCP, OAST, Crawler)
MCP Agent  → MCP Server → Backends (Built-in Proxy or Burp MCP, OAST, Crawler)

Core Files

• sectool/main.go - Entry point; routes mcp subcommand to server mode, else CLI command dispatch
• sectool/config/config.go - Config loading/saving, defaults, auto-creation
• sectool/config/socket_unix.go / socket_windows.go - DefaultSidecarSocket: per-OS sidecar IPC address (Unix domain socket, or loopback TCP on Windows)
• sectool/mcpclient/client.go - MCP client wrapper for CLI usage
• sectool/mcpclient/tools.go - Typed methods for each MCP tool
• sectool/mcpclient/types.go - Client-specific option types (*Opts structs)
• sectool/bundle/bundle.go - Client-side bundle file operations for export

Protocol

• sectool/protocol/workflow.go - Workflow mode constants shared between service and mcpclient
• sectool/protocol/types.go - Shared MCP response types (used by both service and mcpclient)

Service Layer

• sectool/service/server.go - MCP server lifecycle and backend coordination
• sectool/service/mcp_server.go - MCP server setup, tool registration, workflow handling
• sectool/service/mcp_proxy.go - Proxy and flow_get tool handlers (poll, flow_get, cookie_jar, rules)
• sectool/service/mcp_proxy_internal.go - Internal MCP proxy tool (_internal_history_delete)
• sectool/service/mcp_replay.go - Replay tool handlers (send, request_send)
• sectool/service/mcp_crawl.go - Crawl tool handlers (create, seed, status, poll, sessions, stop)
• sectool/service/mcp_oast.go - OAST tool handlers (create, poll, get, list, delete)
• sectool/service/mcp_encode.go - Encode/decode tool handlers (url, base64, html)
• sectool/service/mcp_uuid.go - UUID generation tool handler (v4, v7)
• sectool/service/mcp_hash.go - Hash tool handler (md5, sha1, sha256, sha512, HMAC)
• sectool/service/mcp_jwt.go - JWT decode tool handler
• sectool/service/mcp_diff.go - Diff tool handler (structured flow comparison)
• sectool/service/mcp_reflection.go - Reflection tool handler (parameter reflection detection)
• sectool/service/mcp_jssurface.go - JS analyze tool handler (extract API surface from JS/HTML responses)
• sectool/service/mcp_jsendpoint.go - JS endpoint detail tool handler (per-call-site request shape by deterministic id)
• sectool/service/js/ - JS bundle parser and extractors (tdewolff/parse/v2/js)
• sectool/service/js/analyze.go - main JS bundle analyzer
• sectool/service/js/dedupe.go - deduplication logic
• sectool/service/js/detail.go - per-call-site request-shape extraction (body/headers/query/path params) and deterministic EndpointID
• sectool/service/js/extract.go - extraction logic
• sectool/service/js/html.go - HTML-specific handling
• sectool/service/js/parse.go - parsing logic
• sectool/service/js/scope.go - scoping logic
• sectool/service/js/secrets.go - secrets detection
• sectool/service/mcp_notes.go - Notes tool handlers (save, list) and flow listing attachment
• sectool/service/mcp_respond.go - Proxy responder tool handlers (respond_add, respond_delete, respond_list); native backend only
• sectool/service/flags.go - MCP server flag parsing (--port, --proxy-port, --burp, --workflow, --config, --notes, --sidecar-socket)
• sectool/service/backend.go - HttpBackend, ResponderBackend, OastBackend, CrawlerBackend interfaces
• sectool/service/backend_http_native.go - Native built-in proxy implementation of HttpBackend
• sectool/service/backend_http_native_respond.go - Native backend implementation of ResponderBackend
• sectool/service/backend_http_burp.go - Burp MCP implementation of HttpBackend; hosts burpFlowIndex (flow_id ↔ Burp offset mapping)
• sectool/service/backend_oast_interactsh.go - Interactsh implementation of OastBackend
• sectool/service/smtputil.go - SMTP email header parsing utilities
• sectool/service/backend_crawler_colly.go - Colly-based crawler implementation
• sectool/service/capture_filter.go - BuildCaptureFilter: compiles proxy exclusion patterns from config
• sectool/service/mcp_coreinvoke.go - CoreInvoke dispatch for sidecars: invoke a core MCP tool by name (reuses the handlers agents call; internal tools excluded)
• sectool/service/mcp_replay_originate.go - Native HTTP origination for sidecar sends (originateNative); mirrors request_send, produces an attributable flow
• sectool/service/mcp_sidecar_tools.go - Recomposes the advertised MCP tool list as sidecars connect/disconnect; adds sidecar-conditional params to core tools
• sectool/service/sidecar_replay_sink.go - replayRoutingSink: diverts sidecar-performed replays (annotated replay=true) into the replay history store, else proxy history
• sectool/service/search.go - RE2 pattern compilation with LLM-friendly double-escape correction; flow content matching
• sectool/service/httputil.go - HTTP request/response parsing utilities
• sectool/service/jsonutil.go - JSON read/analysis helpers (flatten, parse list)
• sectool/service/types.go - Service-specific request and internal types
• sectool/service/dedupe/dedupe.go - Order-preserving slice deduplication helpers
• sectool/service/fileutil/fileutil.go - Filesystem helpers (AtomicWriteFile)