> ## Documentation Index > Fetch the complete documentation index at: https://docs.symbioticsec.ai/llms.txt > Use this file to discover all available pages before exploring further. # /pentest command > How the /pentest command runs a blackbox penetration test of a running web app or API The `/pentest` command starts a full blackbox penetration test of a running web application or API, identified by its URL. It needs no source code and no Symbiotic account. The command switches the agent into pentest (attack) mode, where the `pentester` agent collects the engagement details, checks authorization, and then runs the audit with the pentest tool set. The pentest plugin is enabled by default. Opt-out is documented in the plugin options. > [!WARNING] > > Only run `/pentest` against systems you own or are explicitly authorized to test. The command asks for that authorization before it starts, and the agent refuses to continue if it is not given. ## Usage ``` /pentest ``` Run the command without arguments. The agent then collects the target and the engagement settings through the `question` tool. See [Intake](#intake). > [!NOTE] > > The help text documents `/pentest `. The command template, however, tells the agent to collect the target from the operator and not to read it from the command arguments. In practice, the agent asks for the target even if you pass a URL. Enter the URL again when the intake question appears. ## Related command | Command | Description | | - | - | | `/pentest` | Start a full blackbox pentest of a running URL | | `/normal` | Leave pentest (attack) mode and return to the normal `build` agent | `/normal` only switches the agent back. It does not stop a run that is already in progress. ## How it works When you run `/pentest`, the following happens: 1. The command is registered by the pentest plugin (`commands.ts`) and runs the `pentester` agent with a fixed prompt template (`blackbox/command.ts`). 2. The agent calls the `question` tool once to collect the engagement details, and warns you that a full run can take tens of minutes and consume many requests and tokens. The run does not start until you confirm. 3. The agent loads the `blackbox-audit` skill and runs the audit in phases, tracking progress with a live task list (`todowrite`). 4. The agent submits validated findings with `pentest_report` and writes the report files to disk. ### Intake The agent asks the following questions in a single `question` call. You can type your own answer to any of them. | Question | Purpose | Options | | - | - | - | | Target URL | The exact URL to test, for example `https://app.example.com` | Free text | | Scope | Authorization sign-off | `Authorized (recommended)`, `Not authorized` | | Allow-hosts | Extra hosts that may be tested | `Just the target (and its subdomains)` (recommended), or custom hosts | | Auth | How the agent authenticates to the app | `None`, `Session cookie`, `Bearer token in storage`, `Username and password` | | Rate limit | Caps the combined request rate of the tools | `On (recommended)`, `Off (full speed)` | | Content discovery | Depth of the `ffuf` path brute force | `Thorough (~62k, recommended)`, `Quick (~4700, fast)`, `Exhaustive (~220k, slow)` | If the scope answer is `Not authorized`, the agent stops and does not scan the target. After intake, the agent asks one follow-up question when authentication is needed: * **Session cookie:** the cookie as `name=value`, or the whole `Cookie` header if several are needed. * **Bearer token in storage:** the storage (`localStorage` or `sessionStorage`), the key, and the value. * **Username and password:** both values. The agent logs in through the browser using `pentest_creds`. The agent also asks for the token refresh endpoint so that long runs do not lose the session. If you do not know it, the agent finds it by watching the login and token refresh network calls. ### Scope Every network tool takes a `scope` object built from the intake answers: ```json theme={null} { "authorized": true, "allowHosts": [], "rateLimit": true, "wordlist": "thorough" } ``` * `authorized: true` is required. Nothing runs against a target without it. * `allowHosts` is empty by default, which means the target, its API, and its subdomains are in scope. * `egress` defaults to `open`, so SSRF can be proven. Set `egress: "allowlist"` to confine traffic to the listed hosts and to block internal address ranges. * `rateLimit` caps the combined request rate. Set it to `false` to run at full speed. * `wordlist` selects the ffuf wordlist: `quick`, `thorough`, or `exhaustive`. ### Phases The `blackbox-audit` skill drives the run through these phases: | Phase | Work | | - | - | | 0. Setup | Checks the tool toolchain with `pentest_tools action=status` and installs missing tools. Starts the browser with `pentest_browser` and waits for `Browser ready`. Logs in if credentials were given. | | 1. Recon | Maps the external footprint with `pentest_subdomains`, probes live hosts with `pentest_httpx`, fingerprints the stack and versions, runs `pentest_nuclei` for version-based CVE templates, and scans JavaScript bundles for exposed secrets with `pentest_secrets`. | | 2. Discovery | Captures the real surface through the browser and network traffic, then uses `pentest_ffuf`, `pentest_arjun`, `pentest_openapi`, and `pentest_graphql`. Each hit is verified by opening it in the browser and comparing it with a random nonexistent path. Soft 404s and SPA shells are discarded. The agent saves the coverage map with `pentest_coverage`. | | 2b. Testing | Runs the tool matrix against every verified endpoint. Tools are matched to the surface. For example, `pentest_sqlmap` and `pentest_dalfox` run only on endpoints with parameters. | | 3. Hunting | Spawns `web-hunter` subagents, one per surface and attack class, to test DOM XSS, injection, auth and session, IDOR and authorization, CORS, cache, redirect, and SSRF. A `coverage-critic` subagent names surfaces and classes that have not been tested yet. | | 4. Validation and report | Validates candidate findings and submits them with `pentest_report`. Runs `pentest_audit` to prove the traffic stayed within scope. | ### Report `pentest_report` writes the results to `~/.local/share/symbiotic/pentest/` by default. The data home can be changed with the `PENTEST_DATA_DIR` environment variable (or `XDG_DATA_HOME`), and the files go to `/symbiotic/pentest/`. Each run produces these files: | File | Content | | - | - | | `run-.json` | The full run data | | `report-.md` | Markdown report, grouped by verdict and severity | | `report-.html` | Styled HTML report | | `report-.pdf` | PDF of the HTML report, when Chrome is available | | `findings.jsonl` | One line per finding, appended across runs | Credentials are never written to the report. > [!WARNING] > > A full run can take tens of minutes and make a large number of requests and model calls. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.