Initialize a new SecPipe project workspace.

Creates a .secpipe/ directory for storing configuration and execution results. Call this once before using hub tools. The project path is a working directory for SecPipe state — it does not need to contain the files you want to analyze. Use set_project_assets separately to specify the target files.

:param project_path: Working directory for SecPipe state. Defaults to current directory. :return: Project initialization result.

Set the directory containing target files to analyze.

Points SecPipe to the directory with your analysis targets (firmware images, binaries, source code, etc.). This directory is mounted read-only into hub tool containers.

:param assets_path: Path to the directory containing files to analyze. :return: Result including stored assets path.

List all executions for the current project.

Returns execution summaries including server, tool, timestamp, and success status.

:return: List of execution summaries.

Get results for a specific execution.

:param execution_id: The execution ID to retrieve results for. :param extract_to: Optional directory to extract results to. :return: Result including path to results archive.

List all artifacts produced by hub tools in the current project.

Artifacts are files created by tool executions in /app/output/. They are automatically tracked after each execute_hub_tool call.

:param source: Filter by source server name (e.g. "binwalk-mcp"). :param artifact_type: Filter by type (e.g. "elf-binary", "json", "text", "archive"). :return: List of artifacts with path, type, size, and source info.

Get metadata for a specific artifact by its container path.

:param path: Container path of the artifact (e.g. /app/output/extract_abc123/squashfs-root/usr/sbin/httpd). :return: Artifact metadata including path, type, size, source tool, and timestamps.

List available skill packs.

Skill packs provide domain-specific pipeline guidance for AI agents. They describe analysis methodologies and list the hub servers needed. Project-local skills (.secpipe/skills/) override built-in skills.

:return: List of available skills with name, summary, and server list.

Load a skill pack to guide the current analysis session.

A skill pack provides a pipeline description and specifies which hub servers are relevant. Once loaded, the pipeline description is available as context and only the listed servers need discovery.

:param name: Skill name (e.g. "firmware-analysis"). :return: Loaded skill with full description and server list.

Unload the currently active skill pack.

Clears the active pipeline guidance. The agent returns to generic mode.

:return: Confirmation of unload.

List all registered MCP hub servers.

Returns information about configured hub servers, including their connection type, status, and discovered tool count.

:param category: Optional category to filter by (e.g. "binary-analysis", "web-security", "reconnaissance"). Only servers in this category are returned. :return: Dictionary with list of hub servers.

Discover tools from hub servers.

Connects to hub servers and retrieves their available tools. If server_name is provided, only discovers from that server. Otherwise discovers from all enabled servers.

:param server_name: Optional specific server to discover from. :return: Dictionary with discovered tools.

List all discovered hub tools.

Returns tools that have been previously discovered from hub servers. Run discover_hub_tools first if no tools are listed.

:return: Dictionary with list of discovered tools.

Execute a tool from a hub server.

:param identifier: Tool identifier (format: hub:server:tool or server:tool). :param arguments: Tool arguments matching the tool's input schema. :param timeout: Optional execution timeout in seconds. :return: Tool execution result.

Example identifiers:

• "hub:binwalk-mcp:binwalk_scan"

• "hub:yara-mcp:yara_scan_with_rules"

• "hub:nmap:nmap_scan"

FILE ACCESS — if set_project_assets was called, the assets directory is mounted read-only inside the container at two standard paths:

• /app/uploads/ (used by binwalk, and tools with UPLOAD_DIR)

• /app/samples/ (used by yara, capa, and tools with SAMPLES_DIR) Always use /app/uploads/ or /app/samples/ when passing file paths to hub tools — do NOT use the host path.

Tool outputs are persisted to a writable shared volume:

• /app/output/ (writable — extraction results, reports, etc.) Files written here survive container destruction and are available to subsequent tool calls. The host path is .secpipe/output/.

Get the input schema for a hub tool.

Returns the JSON Schema that describes the tool's expected arguments.

:param identifier: Tool identifier (format: hub:server:tool or server:tool). :return: JSON Schema for the tool's input.

Add a new MCP server to the hub.

Register a new external MCP server that can be used for tool discovery and execution. Servers can be Docker images, local commands, or SSE endpoints.

:param name: Unique name for the server (e.g., "nmap", "nuclei"). :param server_type: Connection type ("docker", "command", or "sse"). :param image: Docker image name (for docker type). :param command: Command and args (for command type). :param url: SSE endpoint URL (for sse type). :param category: Category for grouping (e.g., "reconnaissance"). :param description: Human-readable description. :param capabilities: Docker capabilities to add (e.g., ["NET_RAW"]). :param environment: Environment variables to pass. :return: Information about the added server.

Examples:

• Docker: add_hub_server("nmap", "docker", image="nmap-mcp:latest", capabilities=["NET_RAW"])

• Command: add_hub_server("custom", "command", command=["python", "server.py"])

Start a persistent container session for a hub server.

Starts a Docker container that stays running between tool calls, allowing stateful interactions. Tools are auto-discovered on start.

Use this for servers like radare2 or ghidra where you want to keep an analysis session open across multiple tool calls.

After starting, use execute_hub_tool as normal - calls will be routed to the persistent container automatically.

:param server_name: Name of the hub server to start (e.g., "radare2-mcp"). :return: Session status with container name and start time.

Stop a persistent container session for a hub server.

Terminates the running Docker container and cleans up resources. After stopping, tool calls will fall back to ephemeral mode (a new container per call).

:param server_name: Name of the hub server to stop. :return: Result indicating if the session was stopped.

Get status of persistent hub server sessions.

If server_name is provided, returns status for that specific server. Otherwise returns status for all active persistent sessions.

:param server_name: Optional specific server to check. :return: Session status information.

Start a continuous/background tool on a hub server.

Automatically starts a persistent container if not already running, then calls the server's start tool (e.g., cargo_fuzz_start) which launches a background process and returns a session_id.

The tool runs indefinitely until stopped with stop_continuous_hub_tool. Use get_continuous_hub_status to monitor progress.

Example workflow for continuous cargo fuzzing:

1. start_continuous_hub_tool("cargo-fuzzer-mcp", "cargo_fuzz_start", {"project_path": "/data/myproject"})

2. get_continuous_hub_status(session_id) -- poll every 10-30s

3. stop_continuous_hub_tool(session_id) -- when done

:param server_name: Hub server name (e.g., "cargo-fuzzer-mcp"). :param start_tool: Name of the start tool on the server. :param arguments: Arguments for the start tool. :return: Start result including session_id for monitoring.

Get live status of a continuous hub tool session.

Returns current metrics, progress, and recent output from the running tool. Call periodically (every 10-30 seconds) to monitor.

:param session_id: Session ID returned by start_continuous_hub_tool. :return: Current status with metrics (executions, coverage, crashes, etc.).

Stop a running continuous hub tool session.

Gracefully stops the background process and returns final results including total metrics and any artifacts (crash files, etc.).

:param session_id: Session ID of the session to stop. :return: Final metrics and results summary.

List all active and recent continuous hub tool sessions.

:return: List of sessions with their status and server info.

Generate a comprehensive analysis report for the current project.

Aggregates all execution history, tool outputs, and tracked artifacts into a structured report. The report is saved to .secpipe/reports/ and its content is returned so the agent can read it immediately.

:param title: Optional report title. Defaults to the project folder name. :param report_format: Output format — "markdown" (default) or "json". :param output_path: Optional absolute path to save the report. When omitted, the report is saved automatically to .secpipe/reports/. :return: Report content, save path, and counts of included items.

List all generated reports for the current project.

Reports are stored in .secpipe/reports/ and are ordered newest-first.

:return: List of report files with filename, path, size, and creation time.