> For the complete documentation index, see [llms.txt](https://copilot-docs.bugbase.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-an-external-scan/configure-scan-settings-for-external-assessment.md). # Configure Scan Settings for External Assessment Open the settings drawer from **Modules -> External Assessment -> Discovery Phase** or **Modules -> External Assessment -> Attack Phase** by selecting a target and clicking the settings icon. Most settings are saved per root entity and module. The review drawer highlights targets whose latest configuration has not been saved. {% hint style="info" %} **Video walkthrough:** [Configure an external assessment](https://www.youtube.com/watch?v=O5AbZoO-uP4) {% endhint %} {% hint style="info" %} Severity display is configured separately in **Settings -> External -> Severity Display**. Use **CVSS** for standards-aligned severity bands and compliance reporting. Use **VRT** for Bugcrowd-style P1-P5 priority data on external web and API findings. Learn more at [Bugcrowd VRT](https://bugcrowd.com/vulnerability-rating-taxonomy). {% endhint %}
## Authentication Types Choose how the scanner should interact with the target. | Mode | Behavior | Use when | | ------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **Unauthenticated** | Tests public pages and APIs without a logged-in browser session. | Public surface, marketing pages, unauthenticated APIs, login and registration flows. | | **Authenticated** | Reuses one or more recorded browser sessions. Each session represents a role or account state. | Admin/user role testing, RBAC, IDOR, business logic, tenant isolation, account-specific workflows. | | **Both** | Runs unauthenticated and authenticated work. | You want public and logged-in coverage in one run. | Authenticated mode requires at least one browser session. Multiple sessions run separate assessments and are useful for comparing roles. {% content-ref url="/pages/vJW7K5Y9mXnXTl9AXwwo" %} [Recording Browser Session](/enterprise/how-to-trigger-an-external-scan/recording-browser-session.md) {% endcontent-ref %} ## Browser Session Readiness The UI checks selected sessions before launch. A session can be blocked or warned when it lacks persisted login data, usable authentication criteria, replay data, or validation results. If the review drawer reports readiness issues, open the browser session manager, validate the session, or re-record it. {% content-ref url="/pages/qlsZUTSSIvcyvgbeitK1" %} [Validating Browser Sessions](/enterprise/how-to-trigger-an-external-scan/validating-browser-sessions.md) {% endcontent-ref %} ## Starting Paths Starting paths control where browser work begins. * **Unauthenticated starting path** defaults to `/`. * **Authenticated starting path** defaults to `/`. Use specific paths when the target has a known entry point, such as `/login`, `/dashboard`, `/admin`, or a tenant-specific route. ## Discovery Type This appears on the discovery page. | Option | Behavior | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | **Run Full Discovery** | Crawls reachable endpoints and user flows. This is required if discovery should feed the attack phase. | | **Discover Domains only** | Maps domain and subdomain surface without deep crawling. | ## Auto-Run External Assessment When **Trigger Attack Phase automatically after discovery** is enabled, Pentest Copilot starts the external assessment after discovery finishes. This option forces full discovery because the attack phase needs pages, APIs, and trajectories to test. Use this for unattended discovery-to-assessment runs. Leave it disabled when your team wants to review the discovered surface before active testing. ## Attack Vectors Attack vectors choose which vulnerability categories are tested. The External Assessment settings drawer accepts these category IDs: ``` AUTHENTICATION OPEN_REDIRECT AUTHORIZATION BUSINESS_LOGIC CACHE COMMAND_INJECTION CSRF DIRECTORY_TRAVERSAL FILE_UPLOAD IDOR INFORMATION_DISCLOSURE JWT MASS_ASSIGNMENT NOSQL_INJECTION OAUTH PROMPT_INJECTION PROMPT_LEAKAGE PROTOTYPE_POLLUTION REQUEST_SMUGGLING SAML SERIALIZATION SQL_INJECTION SSTI SSRF WEBSOCKETS XML XSS ``` Leaving the list empty is treated as broad coverage. ## Rate-Limit & Egress This section controls three related things: 1. **Where the traffic comes from** using the selected egress. 2. **How fast the scan is allowed to send requests** using the rate limit. 3. **How much browser work can run in parallel** using the calibrated recommendation and the optional operator cap.

Configure rate limit and egress

### Egress The selected egress changes the source IP and therefore the target's observed behavior. | Egress | Behavior | Use when | | ---------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **SANDBOX egress** | Browser traffic comes from the Pentest Copilot SANDBOX agent IPs. | The target can allowlist scanner IPs, traffic must come from a predictable address, or residential proxies are not allowed. | | **Residential proxy egress** | Browser traffic comes from a residential proxy IP instead of the SANDBOX IP. | Bot defenses or CDN/WAF rules block datacenter traffic and the target allows testing from rotating residential IPs. | The page shows the SANDBOX public IPs used for external browser traffic. Share those with the target team when firewall, CDN, or WAF allowlisting is required. ### Use Rotating Residential IPs This option appears only when **Residential proxy egress** is selected. By default, a residential run keeps one stable residential exit IP for the whole scan. Enable **Use rotating residential IPs** to spread the scan across the residential proxy pool instead: each browser or scanning job in the run leaves from the next IP in the pool, rotating through many exit IPs. | Setting | Behavior | Use when | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Off** (default) | Every job in the scan uses one fixed residential exit IP. | The target's defenses or session handling expect a consistent client IP. | | **On** | Each job uses the next residential IP in rotation, so consecutive requests are distributed across many exit IPs. | The target throttles or challenges by source IP, or a single residential IP gets rate-limited on longer runs. | {% hint style="info" %} Rotation happens per job. A single job (for example one browser flow) still uses one exit IP for all of its own requests, so login and multi-step flows stay on a consistent IP within that job. {% endhint %} ### Rate Limit (req/min) **Rate Limit** caps requests per minute for the selected target. Use a lower value when: * the target is production and fragile; * your organization has strict rate limits or WAF thresholds; * authenticated sessions are easily invalidated; * the application performs expensive server-side operations. Leaving the value blank means no explicit per-target cap is applied. Selecting **No rate limit** tells Pentest Copilot to scan at maximum speed. ### Auto-Calibrate **Auto-calibrate** estimates a sustainable request rate for the currently selected egress. It uses the same selected browser session and custom headers where applicable. Auto-calibration runs in two phases: 1. **Page-footprint census** measures how "expensive" a real browser page is for the target. Pentest Copilot observes both the scan starting URL and, when an authenticated browser session is selected, the session's authentication verification URL. It records: * the initial page-load burst; and * the ongoing steady request rate for one browser tab. 2. **Rate-limit probe** ramps request traffic until the target starts throttling or blocking, then stores a recommended per-target request budget for the selected egress. The drawer then shows: * the calibrated **Result** in requests per minute; * a **Confidence** score for that calibration; * **Recommended max submodules**, derived from the calibrated request budget and the measured page footprint. If you manually change the rate limit after calibration, the **Recommended max submodules** value updates live in the UI using the same measured page footprint and your new request budget. {% hint style="warning" %} Auto-calibration sends intentional probe traffic and may issue a few hundred requests across the census and probe phases. Use it only when that traffic is approved. {% endhint %} If every request is blocked, the UI warns that the target is rate-limiting the selected egress. In that case: * with **SANDBOX egress**, allowlist the SANDBOX IPs on your firewall, CDN, or WAF; * with **Residential proxy egress**, switch back to SANDBOX egress or use a conservative manual rate limit if residential traffic is blocked or unstable in your environment. ### Max Submodules **Max Submodules** is an optional operator cap on how many submodules can run at once for that target. Use it when you want to be more conservative than the calibrated recommendation, for example when: * the target has burst-sensitive workflows; * authenticated sessions are fragile; * a business workflow has expensive writes or background jobs; * you want to slow one target without lowering the whole workspace. Leave it empty to let the calibrated recommendation be the only concurrency ceiling. When both values exist, Pentest Copilot uses the lower of: * **Recommended max submodules** from calibration; and * your configured **Max Submodules** value. This means the manual cap can lower concurrency, but it does not raise concurrency above what calibration considers sustainable. ### Max Concurrent Jobs (Agent) **Max concurrent jobs** optionally sets how many jobs the agent running this scan may execute at the same time, for the duration of the scan. It overrides the agent's default job concurrency and is automatically restored when the scan ends. Use it to: * raise throughput on a dedicated, well-resourced agent for a large target; or * lower agent load for fragile targets, or when an agent is shared with other work. Leave it empty to use the agent's configured concurrency. {% hint style="info" %} This is different from **Max Submodules**. **Max Submodules** caps how many submodules run at once for this target; **Max concurrent jobs** sets the total job concurrency on the agent itself. If several scans share one agent, the most recently started scan's value applies while it runs, and the agent returns to its normal concurrency once these scans finish. {% endhint %} ## Trajectory Scope Trajectories are discovered user flows or API sequences. The settings drawer lets you narrow the run to specific trajectories. You can: * search by label, summary, ID, host, path, or method; * filter by single API, grouped multi-API, cleaned multi-API, or all flows; * filter by HTTP method; * select or deselect individual flows; * select or clear the current page; * select or deselect all. The saved configuration stores deselected trajectory IDs. This means newly discovered trajectories are included unless explicitly excluded later.
## Custom Headers Custom headers are sent with scan traffic for the selected target. Use them for approved headers such as: * tenant selectors; * feature flags; * testing bypass headers; * API gateway headers; * WAF allowlist headers; * non-secret test tokens. Do not store production secrets in documentation or screenshots. ## Advanced Options ### Ignore 404 Check Keeps pages that the platform might otherwise classify as custom 404 pages. Enable when valid app routes look similar to error pages or when 404 pages are intentionally in scope. ### Fail Module on Invalid Session Stops the module when a selected browser session is invalid, expired, logged out, or cannot be regenerated. Use this when a partial authenticated run would produce misleading results. ### Skip Browser Session Validation Skips pre-run browser-session validation checks. Use only when your team accepts the risk of session-related failures or when a known validation edge case blocks a session that has been manually confirmed as usable. ### Use Residential IP for Browser Traffic Routes browser traffic through a residential proxy. This helps when bot defenses block datacenter SANDBOX traffic. Disable it when the target is internal, allowlists only the SANDBOX IP, or must see traffic from a specific source in your environment. ### Isolate Browser Per Job Runs browser jobs with stronger isolation to reduce stale pages, cookie collisions, and shared browser state issues. This can improve reliability but may make scans slower. ### Use Shared Browser Instance Runs multiple tabs per browser driver. This can reduce browser startup overhead but may reduce isolation. Use it when targets dislike frequent browser launches and session state is stable across tabs. ### Max Crawler Runs Limits crawler runs for discovery. Use it to cap exploration on very large or unbounded applications. ## Manual Crawler Manual Crawler opens a proxied browser so an operator can navigate important flows and save them as trajectories. Use it when: * the app requires complex human navigation; * discovery misses a flow; * a workflow needs specific seeded data; * an authenticated role has important functionality behind menus or multi-step state. {% content-ref url="/pages/Qe2U4mKd2ubu7USVan3H" %} [Manual Crawler](/enterprise/how-to-trigger-an-external-scan/manual-crawler.md) {% endcontent-ref %} ## Scan Estimate and Runtime Limit The review drawer shows estimated duration and scan-hour usage. Estimates can change based on queue depth, worker capacity, selected authentication modes, trajectory count, target count, and whether the workspace runs one worker or parallel workers. If a **Max module runtime** setting is configured, the review drawer warns that unfinished submodules will be cancelled after that limit. ## Save Configuration and Schedule Before running or scheduling: 1. Open settings for each target. 2. Save the configuration. 3. Review the drawer for missing saved config warnings. 4. Start immediately or schedule the run from the final review drawer. Schedules are created from the same run review used for immediate launches. They reuse the target payload and scan configuration included when the schedule is created. Recreate or update schedules after changing important settings such as sessions, rate limits, attack vectors, trajectory exclusions, or target scope. Manage existing schedules from **Activity -> Schedule**.