Purpose: Run Nmap using mode=quick|aggressive|port|script|custom for host discovery, service enumeration, NSE execution… Constraints: quick/aggressive/port/script require target. port requires ports. script requires scripts. extra_args is preserved for quick, aggressive, port, and script modes.… Example: nmap_scan(mode='quick', target='scanme.nmap.org')

Purpose: Write a custom NSE script into the container and update the Nmap script database. Constraints: Pass name without path separators; Hercules sanitizes it and writes /opt/workspace/nmap-scripts/.nse. Use nmap_run_nse_script to execute that managed artifact.… Example: nmap_write_nse_script(name='http-custom-check', content='description = [[...]]\nauthor = ...')

Purpose: Run a previously written custom NSE script against a validated target. Constraints: Requires target and script_name. extra_args can pass -p, -sV, --script-args, --script-trace, -d, or -v. XML output is parsed when possible, preserving script output fields. Example: nmap_run_nse_script(target='host', script_name='http-custom-check', extra_args='-p80 --script-trace')

Purpose: Search Metasploit exploit, auxiliary, and post modules by keyword, service name, or CVE. Constraints: Returns available modules that may help with the query. Broaden the query if the list is empty. Metasploit must be enabled and RPC available. Example: metasploit_search(query='vsftpd')

Purpose: Run a Metasploit exploit, auxiliary, or post module through the RPC API. Constraints: module_type is usually exploit, auxiliary, or post. options should contain module datastore options such as RHOSTS/RPORT/TARGETURI. payload and payload_options are used for exploits.… Example: metasploit_run_module(module_type='exploit', module_name='unix/ftp/vsftpd_234_backdoor'…

Purpose: Manage Metasploit sessions and jobs with action=list_sessions|interact_session|close_session|list_jobs|stop_job. Constraints: interact_session requires session_id and command. close_session requires session_id. stop_job requires job_id.… Example: metasploit_manage(action='list_sessions')

Purpose: Generate a payload through Metasploit RPC or msfvenom fallback. Constraints: Pass payload and options such as LHOST/LPORT. format controls output format. Successful RPC generation writes payload bytes into /opt/workspace/payloads/. Example: metasploit_generate_payload(payload='linux/x86/meterpreter/reverse_tcp'…

Purpose: Start exploit/multi/handler as a Metasploit background job. Constraints: Requires payload_type, lhost, and lport. lport must be 1-65535. Use system_network_info first to choose LHOST/LPORT on bridge-networked hosts. Manage jobs with metasploit_manage. Example: metasploit_start_listener(payload_type='linux/x86/meterpreter/reverse_tcp', lhost='10.0.0.1', lport=4444)

Purpose: Run sqlmap with action=scan_basic|scan_custom|enumerate|dump|os_cmd. Constraints: Requires target_url and target validation. Always uses --batch and a workspace output directory. scan_custom supports method, data, cookies, level, risk, techniques, tamper, proxy, forms… Example: sqlmap_run(action='scan_basic', target_url='http://host/item?id=1')

Purpose: Run Nuclei templates against one or more targets with JSONL output. Constraints: targets is comma-separated. templates can point to a workspace template from nuclei_write_template or installed template paths. severity, tags, rate_limit, and extra_args tune execution.… Example: nuclei_run(targets='http://host', templates='/opt/workspace/nuclei-templates/check.yaml', rate_limit=5)

Purpose: Write a custom Nuclei YAML template into /opt/workspace/nuclei-templates. Constraints: Path traversal is rejected. Use relative paths such as custom/check.yaml. Validate with nuclei -validate via shell_exec or run with nuclei_run using the returned path. Example: nuclei_write_template(path='custom/basic-detect.yaml', content='id: basic-detect\ninfo: ...')

Purpose: Search or mirror Exploit-DB entries with action=search|get. Constraints: Search returns JSON when available and may degrade overly specific queries to broader terms. include_raw=True avoids result capping.… Example: searchsploit(action='search', query_or_id='apache 2.4')

Purpose: Execute a non-interactive shell command inside the Kali container. Constraints: raw=True disables semantic compaction but retains safety bounds and artifacts. This is non-interactive; use shell_exec_background or ncat/listeners for long-running jobs. Example: shell_exec(command='id && pwd')

Purpose: Start a long-running shell command as a background job. Constraints: Requires job_id. Use shell_check_job to read output and shell_kill_job to stop the process. Background jobs share the current container session. Example: shell_exec_background(command='python3 -m http.server 8000', job_id='http8000')

Purpose: Read status and tail output from a background shell job. Constraints: Requires job_id. tail_lines controls how much recent output is returned. If output is too short, increase tail_lines or inspect artifacts with workspace_read_file/shell_exec. Example: shell_check_job(job_id='http8000', tail_lines=100)

Purpose: Stop a background shell job by job_id. Constraints: Requires job_id. Use shell_check_job first if you need final output. The response says whether a process was killed. Example: shell_kill_job(job_id='http8000')

Purpose: Read a bounded file chunk inside the owned container workspace. Constraints: Relative paths resolve under /opt/workspace. Paths outside it and symlink/reparse escapes are rejected. encoding='base64' reads binary data. For large files… Example: workspace_read_file(path='nuclei-templates/custom/check.yaml')

Purpose: Atomically write content to a file in the owned container workspace. Constraints: Relative paths resolve under /opt/workspace; paths outside it and symlink/reparse escapes are rejected. Supply either content or content_base64, never both. mode defaults to 0644.… Example: workspace_write_file(path='targets.txt', content='http://host\n')

Purpose: Start a fresh Hercules container session with a clean mounted workspace. Constraints: Creates a new workspace and stops the current container. Previous host workspace data is preserved. Metasploit RPC is reinitialized when enabled. Example: system_start_new_session()

Purpose: List Hercules session workspaces on the host. Constraints: Returns active_session, total_sessions, and per-session metadata where available. Does not modify the container. Example: system_list_sessions()

Purpose: Stop and remove the current Hercules container while preserving workspace files. Constraints: After this tool succeeds, MCP tools that require the container cannot run until a new session is started. It stops background jobs and container-side processes. Example: system_stop_container()

Purpose: Inspect host/container networking, browser host access, and callback routes. Constraints: Returns effective RPC/listener/stream ports, LHOST guidance, localhost scope, and the Docker-host alias. Concurrent IDE clients may receive different ports. Example: system_network_info()

Purpose: Collect WHOIS registration data for a domain. Constraints: Use include_raw=True if registry boilerplate or exact legal text is needed. Default output preserves registrar, dates, nameservers, statuses, DNSSEC… Example: recon_whois(domain='example.com')

Purpose: Enumerate subdomains with amass using passive, active, and brute-force modes. Constraints: Requires domain and validates it. active=False uses passive mode. brute=True enables brute force. This is heavy and can take up to 20 minutes. Example: recon_amass(domain='example.com', active=False)

Purpose: Run DNS lookups with tool=dig|dnsx for single-record queries or bulk resolution. Constraints: dig uses target, record_type, server, short, axfr, and extra_args. dnsx uses domains or target and silent/extra_args.… Example: recon_dns(tool='dig', target='example.com', record_type='MX', short=True)

Purpose: Run one web fingerprinting scanner selected by tool=httpx|whatweb|wafw00f|nikto|wpscan|arjun. Constraints: httpx accepts urls or target and supports threads. whatweb uses agg_level. nikto supports tuning. wpscan supports enumerate and api_token. arjun supports method and threads.… Example: web_scan(tool='httpx', urls='http://a,http://b', threads=20)

Purpose: Discover web paths with gobuster or ffuf while preserving thread control. Constraints: Requires target_url. tool defaults to gobuster; ffuf is selected with tool='ffuf'. threads controls native fuzzer concurrency. Missing wordlists return repair guidance and example paths.… Example: fuzz_dirs(target_url='http://host', wordlist='/usr/share/wordlists/dirbuster/directory-list-2.3-medium.tx…

Purpose: Run web vulnerability scanners selected by tool=dalfox|commix. Constraints: Requires target_url. Dalfox maps threads to --worker and supports cookie and extra_args. Commix supports data, cookie, threads when native support exists, and extra_args.… Example: web_vuln_scan(tool='dalfox', target_url='http://host/?q=1', threads=8)

Purpose: Make HTTP requests with curl using methods, headers, cookies, data, redirects, and extra curl arguments. Constraints: The URL is target-validated. Output is mostly raw aside from terminal cleanup and truncation. Use headers as comma-separated Header: value strings.… Example: network_curl(url='http://host/path', method='POST', data='a=1', cookie='sid=1')

Purpose: Use ncat with action=connect|listen|interact for TCP/UDP connections and background listeners. Constraints: connect requires target and port and runs foreground. listen can run foreground or background; background=True creates a job_id and pipe.… Example: ncat(action='listen', port=4444, job_id='listener1')

Purpose: Craft packets with hping3 for firewall, service, or packet-level testing. Constraints: Requires target. count, syn, port, and extra_args map to hping3. Runs with light concurrency and target validation. Example: network_hping3(target='host', count=3, syn=True, port=80)

Purpose: Run Hydra for online credential testing against a service. Constraints: Requires target, service, usernames, and passwords. Prefix usernames/passwords with file: for wordlists. Target is validated. Output summary keeps credential findings. Example: bruteforce_hydra(target='host', service='ftp', usernames='msfadmin', passwords='msfadmin')

Purpose: Run John the Ripper against supplied hashes using a wordlist. Constraints: Hashes are written to a temporary workspace file, cracked with john, shown with john --show, then the temp file is removed. Use format and extra_args when hash type needs explicit selection. Example: crack_john(hashes='$y$j9T$...', format='crypt', wordlist='/usr/share/wordlists/rockyou.txt')

Purpose: Analyze and optionally extract firmware, archives, and embedded files with binwalk. Constraints: extract=True adds extraction flags and --run-as=root unless extra_args already specifies --run-as. Absolute paths extract from their containing directory to avoid duplicate paths. Example: ctf_binwalk(filepath='/opt/workspace/sample.bin', extract=True)

Purpose: Inspect or extract steghide payloads with action=info|extract. Constraints: Pass filepath and optional passphrase. Without a passphrase Hercules passes an empty one to avoid an interactive prompt. extra_args can tune steghide behavior. Example: ctf_steghide(action='info', filepath='/opt/workspace/image.jpg')

Purpose: Open a URL in cloakbrowser Chromium and start an interactive browsing session.… Constraints: url is scope-validated and redirects are revalidated. fingerprint is compatibility-only and non-empty values are rejected. Proxy precedence is parameter, BROWSER_PROXY_URL, then direct… Example: browser_open(url='https://app.target.test/login', session='recon', timezone='America/New_York'…

Purpose: Capture the page's accessibility tree as compact text with stable element references (@e1, @e2, ...).… Constraints: compact is default; detailed requests an uncompacted unlimited-depth tree. Use interactive, include_urls, depth, or selector to narrow/expand it. Iframes auto-inline… Example: browser_snapshot(session='recon')

Purpose: Interact with a page element: click, fill, type, press a key, hover, select an option, or (un)check.… Constraints: Use browser_snapshot refs when available. ref/CSS supports all actions. Semantic role/text/label supports click, fill, check, and hover only; use name/exact for accessible matching. Example: browser_act(action='fill', target='e3', value='admin', session='recon')

Purpose: Read data from the page: visible text, inner HTML, an input value, or the page-level URL/title.… Constraints: url/title are page-level. ref/CSS supports text/html/value; semantic role/text/label supports text only with optional name/exact. Use snapshot/ref or CSS for unsupported combinations. Example: browser_read(what='url', session='recon')

Purpose: Capture a validated PNG screenshot of the current page as native inline MCP image content and save it into the container work… Constraints: Shots save to /opt/workspace/browser// by default. A relative path resolves under that per-session directory and rejects '..'. full=True captures the scrollable page.… Example: browser_screenshot(session='recon')

Purpose: Run arbitrary JavaScript in the page context and return the result. Use for custom DOM extraction, probing JS state… Constraints: The JS is written to a workspace temp file and evaluated to avoid quoting issues. Return a JSON-serializable value (wrap objects in JSON.stringify) for clean output.… Example: browser_eval(js="JSON.stringify({wd: navigator.webdriver, plugins: navigator.plugins.length})"…

Purpose: Wait for a condition before continuing: an element/selector to appear, a fixed number of milliseconds, specific text… Constraints: condition selects the mode: selector (CSS/@ref in value), ms (milliseconds in value), text (value is the text to await), url (value is a URL glob like '**/dashboard')… Example: browser_wait(condition='load', value='networkidle', session='recon')

Purpose: Manage isolated stealth browser identities and the optional loopback-only live-view stream. Each session has its own cookies… Constraints: action selects current, list, close, close_all, or stream. Stream discovers the selected session's loopback WebSocket and safely relays it to the configured host port.… Example: browser_session(action='list')

Purpose: Load agent-browser's own built-in skill documentation — the authoritative… Constraints: With no name it lists available skills; name='core' (default) with full=True returns the complete command reference.… Example: browser_skill()

Purpose: Escape hatch that runs ANY agent-browser command against the current stealth session — giving access to the COMPLETE browser… Constraints: Call browser_skill(name='core', full=True) first. args is raw administrator input for controller features absent from structured tools… Example: browser_cmd(args='cookies list', session='recon')