# Overview Pentest Copilot Enterprise documentation. Pentest Copilot Enterprise helps security teams scope, run, and review external, internal, cloud, and code assessments from one control plane. It combines agent-based execution, browser automation, attack-path analysis, validated findings, scheduling, reporting, and API/MCP automation. ## Assessment Types | Assessment | What it covers | What you provide | | ------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | **External** | Internet-facing domains, pages, APIs, services, authenticated flows, and vulnerability testing. | Approved domains, intent, authentication coverage, rate limits, and attack vectors. | | **Internal** | Reachable networks, hosts, services, identities, trust relationships, and approved exploit validation. | A connected agent, subnet scope, intent, exploit families, and safety controls. | | **Cloud** | AWS, Azure, and Google Cloud inventory and approved active validation through an attached workload identity. | A cloud-hosted agent, provider permissions, discovered scope, test categories, and rollback choices. | | **Code** | Source-code risks, dependencies, secrets, authorization and business logic, SBOM, and AI-BOM. | GitHub App access, repositories, branches/PRs/commits, checks, and automation rules. | ## Run Assessment External and internal work starts from **Modules -> \[assessment type] -> Run Assessment**. Choose one intent: * **Discovery** maps the selected environment without active vulnerability testing. * **Assessment** tests inventory that has already been discovered. * **Discovery + Assessment** refreshes inventory and then assesses what was found. The wizard then guides you through **Scope**, **Scan settings**, **Automation**, and **Review**. Code Assessment uses the same flow without an Intent step.
External Run Assessment intent step showing Discovery, Assessment, and Discovery plus Assessment

Select the outcome you need before configuring scope.

## Main Navigation | Area | Use it for | | ------------- | --------------------------------------------------------------------------------------- | | **Dashboard** | Deployment readiness, mission status, agents, target entities, and the exploit graph. | | **Modules** | Configure runs and review Statistics, Attack Paths, and code inventories. | | **Activity** | Monitor runs, inspect logs, cancel work, and manage schedules. | | **Reports** | Generate executive and comprehensive reports. | | **Settings** | Manage scope, verification, agents, integrations, API keys, users, and tenant defaults. | ## Recommended First Run 1. Confirm your role has the required scan and settings permissions. 2. Add approved external domains or connect the internal/cloud agent that can reach the intended scope. 3. Verify external domain ownership when required. 4. For authenticated external testing, record and validate one browser session per user role. 5. Open the applicable **Run Assessment** page and start with **Discovery** or **Discovery + Assessment**. 6. Keep the first scope narrow and use conservative rate limits or exploit selections. 7. Confirm the complete configuration on **Review**, then choose **Start run** or **Schedule run**. 8. Monitor the run under **Activity**, triage findings under **Attack Paths**, and generate reports when the assessment is complete. {% hint style="warning" %} Pentest Copilot applies the same launch policy to UI, API, and MCP requests. Permissions, feature access, usage limits, scope controls, verification, and worker availability cannot be bypassed by changing the launch method. {% endhint %} See [Scan Noise and Safety](/enterprise/scan-noise-and-safety) before testing production or stateful environments. For onboarding or engagement-specific questions, contact `queries@bugbase.ai`. # Enterprise Onboarding Checklist A practical checklist for preparing a first enterprise scan. Use this checklist before your first enterprise scan. It is written for operators who will configure and run scans, and for security stakeholders who need to approve scope. ## Access and Tenant Setup * Sign in to the deployment URL through your configured identity provider. * Confirm the initial users have the correct roles for scans, reports, settings, API keys, and user management. * Confirm who owns scan approvals, agent installation, and cleanup. ## External Assessment Prerequisites * Collect approved root domains and any explicitly excluded third-party domains. * Add root domains from Target Assets; the External Run Assessment **Scope** step links to that page. * Verify root-domain ownership in **Settings -> Domain Verification** when required by your deployment. * Confirm your team understands that subdomains are discovered automatically from the root domain. * Decide whether target WAF/CDN/firewall rules should allowlist the scanner IPs, use residential browser traffic, or both. * Record browser sessions for each role that should be tested, such as admin, manager, regular user, read-only user, or support user. * Validate browser sessions before running authenticated scans. * Define rate limits for fragile, rate-limited, or production-sensitive targets. * Define domain and trajectory deny rules before scanning sensitive paths. ## Internal Assessment Prerequisites * Identify the network segment where the local agent will run. * Confirm the agent host can reach the approved subnets and required services. * Confirm endpoint protection, EDR, firewall, and proxy expectations for the agent host. * Confirm which exploit families are authorized, especially AD write operations, ADCS abuse, RCE, credential dumping, relay, and data-copy paths. * Confirm cleanup ownership for AD/ADCS changes, host implants, service changes, credential rotation, and copied files. * Decide whether PCE Intercept/Inveigh may be enabled, and which interfaces it may bind to. * Run internal discovery before internal assessment so subnets, hosts, services, users, and groups are visible. {% content-ref url="/pages/Wo8uaAQGOpoDSX3mEaRZ" %} [Internal Assessment Destructive Actions](/enterprise/how-to-trigger-an-internal-scan/internal-assessment-destructive-actions) {% endcontent-ref %} ## Cloud Assessment Prerequisites * Choose a dedicated EC2, Azure VM, or Compute Engine host inside the approved scope. * Attach a dedicated cloud identity and record its baseline permissions. * Confirm native instance metadata is reachable from the agent process. * Define the applicable provider boundary: AWS region and optional literal resource-name prefixes, Azure resource group, GCP project, or the approved hybrid combination. * Grant discovery read access before adding active permissions. * Enable only the provider APIs required by the approved inventory. * Confirm provider audit logs, monitoring, and cleanup ownership. * Approve cloud exploit categories, temporary permissions, rollback, credential rotation, and stop conditions. * Run cloud discovery before active assessment and review every partial collector. {% content-ref url="/pages/cycdJfiZOF1JvOhhmyH7" %} [Run a Cloud Assessment](/enterprise/how-to-trigger-a-cloud-assessment) {% endcontent-ref %} ## First Scan Plan For the first run, start narrow: 1. Open **External Assessment -> Run Assessment** for one root domain. 2. Choose **Discovery + Assessment**, or choose **Discovery** first when active testing has not yet been approved. 3. Record and validate one low-risk authenticated browser session when logged-in coverage is required. 4. Use a conservative rate limit and only approved attack vectors. 5. Confirm the full configuration in **Review**, then start the run. 6. Review **Activity** and **Attack Paths** with security stakeholders. 7. Generate the required reports and expand scope only after the team is comfortable with traffic and results. For internal assessment, choose the appropriate intent and start with one agent-reachable subnet and a small exploit set. Add destructive categories only after sign-off on impact and cleanup. For cloud assessment, start with one dedicated Pentest Copilot agent deployed on a VM in the customer cloud environment. Grant discovery-only permissions first. Add active categories and temporary provider permissions only after scope and cleanup review. # Scan Noise and Safety Understand scan traffic, loudness, safety controls, and operational edge cases. Pentest Copilot can run quiet discovery, browser-based crawling, contextual web/API testing, and active internal exploitation. The right configuration depends on your engagement rules, production sensitivity, target defenses, and appetite for proof-of-impact. ## Noise Levels | Activity | Typical noise | Notes | | --------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | External domain discovery | Low to medium | DNS, certificate, search, and service enumeration. Volume depends on domain size. | | External web crawling | Medium | Sends browser and HTTP requests to discovered pages and APIs. Use rate limits for fragile targets. | | External authenticated assessment | Medium to high | Replays logged-in sessions and tests application-specific flows. Multiple roles increase traffic. | | External attack vectors | Medium to high | Injection, authorization, upload, SSRF, XSS, business-logic, and related tests may trigger WAF/EDR/app alerts. | | Manual crawler | Operator-controlled | In Debug Mode, traffic is generated by the operator's manual navigation through a proxied browser. | | Internal discovery | Medium | Scans reachable hosts/services from the selected agent. May be visible to NDR/EDR. | | Internal assessment | High when exploit categories are enabled | Can authenticate, attempt lateral movement, run commands, relay NTLM, copy files, deploy callbacks, or change AD/ADCS state depending on selected categories. | | Cloud control-plane discovery | Low to medium | Calls provider read APIs through the identity attached to the agent VM and creates provider audit events. | | Cloud assessment | Medium to high | Can read cloud data or change identity, workload, network, logging, storage, key, and recovery state, depending on selected categories. | ## External Safety Controls * **Domain whitelist:** Approved domains that may be tested. * **Domain blacklist:** Domains that must not be tested. Blacklist wins over whitelist. * **Trajectory scope:** Per-host path rules and per-run trajectory selection restrict which APIs/user flows are tested. * **Authentication mode:** Choose unauthenticated, authenticated, or both. Authenticated mode requires browser sessions. * **Browser-session readiness:** The scanner warns when selected sessions lack usable login state or validation data. * **Rate limit:** Caps request volume for the target. * **Auto-calibration:** Sends probe traffic to estimate a sustainable rate. This can send up to 400 requests in short bursts. * **Residential browser IP:** Routes browser traffic through a residential proxy when bot defenses block datacenter traffic. * **Custom headers:** Adds required test headers, API keys, tenant selectors, or WAF bypass headers where approved. * **Max module runtime:** Cancels remaining work if the configured runtime limit is reached. ## Internal Safety Controls * **Agent placement:** Internal scans run from your network through a connected agent. * **Subnet selection:** Operators select specific subnets before running internal assessment. * **Agent assignment:** Each selected subnet has an assigned agent. Agents in the same subnet are prioritized. * **Entity exclusion:** Hosts, users, groups, and services can be excluded from a selected subnet. * **Allowed exploits:** Exploit families are enabled or disabled per subnet. * **Destructive-action warnings:** High-impact categories are highlighted in the final review. * **PCE Intercept/Inveigh:** NTLM capture/relay is opt-in and requires selected network interfaces. * **RCE skip controls:** Operators can skip RCE when the graph already marks the host or user as compromised. ## Cloud Safety Controls * **Machine-attached identity:** Provider access comes from the identity attached to the selected cloud virtual machine. * **Detected scope:** Discovery creates a bounded cloud scope from provider instance metadata. * **Allowed exploits:** Cloud exploit categories can be disabled before starting an Assessment intent. * **Pre-existing vulnerability validation:** Retest mode runs eligible stored exploitation paths without normal host and service fan-out. * **Rollback:** Supported provider changes can be queued for restoration after attack work finishes. Rollback is opt-in and does not cover every action. * **Regional monitoring coverage:** Regional defense-evasion checks require a current, versioned inventory that explicitly marks the selected region as unmonitored. * **Runtime limit:** Remaining cloud work can be cancelled when the module reaches the configured maximum runtime. ## When to Slow Down Use conservative settings when: * the target is production and has strict SLOs; * the application has aggressive WAF, bot, or rate-limiting controls; * login sessions expire quickly or allow only one active session; * user flows trigger emails, payments, state transitions, or external integrations; * internal testing touches domain controllers, ADCS, privileged groups, production databases, or file shares; * cloud testing can change production IAM, workloads, network controls, logging, keys, storage, or recovery resources; * your team wants discovery-only evidence before active exploitation. ## Edge Cases to Plan For * **Bot detection during recording:** Enable residential browser traffic or allowlist SANDBOX IPs. * **Single-session applications:** Enable browser isolation options when multiple tabs or shared state cause forced logout. * **Expired browser sessions:** Re-record or validate sessions before running authenticated scans. * **Manual crawler windows:** Manual Crawler is Debug Mode only. Keep the proxied browser open until trajectories are saved and cancel it from the UI if needed. * **Internal route mismatch:** If no hosts appear after internal discovery, verify the agent's route to the subnet and local firewall rules. * **Responder interface mismatch:** PCE Intercept/Inveigh cannot start until at least one valid interface is selected for the chosen agent. * **Partial cloud discovery:** Validated data may be imported even when a provider operation fails. Fix the failed operation and rerun before judging coverage. * **Cloud rollback failure:** Check rollback status and provider audit logs, then restore unsupported or unverifiable changes manually. * **Scheduled scans:** Schedules reuse saved scan configuration. Review saved configs when scope, sessions, or agent availability changes. # How to Trigger an External Scan Configure and start an external discovery or assessment run. Open **Modules -> External Assessment -> Run Assessment**. The same wizard handles discovery-only runs, assessment-only runs, and runs that perform both in sequence. ## 1. Choose the Intent | Intent | Use it when | | -------------------------- | ----------------------------------------------------------------------------------------------------- | | **Discovery** | You need to map domains, IPs, services, pages, APIs, and browser flows without vulnerability testing. | | **Assessment** | The target surface has already been discovered and you want to test it. | | **Discovery + Assessment** | You want to refresh the target surface and assess the resulting inventory in one run. | Choose **Discovery + Assessment** for a first comprehensive run. Use **Assessment** only when the existing discovery data is current enough for the engagement.
External Run Assessment intent choices

Intent replaces the former separate discovery and attack pages.

## 2. Select Scope Select one or more approved domains or IP targets. The list shows verification and whitelist status. * Use **Manage target assets** when a required domain is missing. Target creation remains in the dedicated scope-management page. * A target that requires ownership verification or whitelisting must pass those checks before launch. * Select each asset in **Configure selected asset** to set its authentication and starting URL independently.
External Scope step with example.com selected

Verification, whitelisting, and per-asset coverage are visible in Scope.

### Authentication Coverage Choose either or both contexts: * **Unauthenticated** tests the public surface without cookies or recorded login state. * **Authenticated** runs each selected browser session independently. Use separate sessions for roles whose permissions should be compared. An optional starting URL can direct a context to a specific full URL or absolute path. Leave it empty to start from the domain root. {% content-ref url="/pages/vJW7K5Y9mXnXTl9AXwwo" %} [Recording Browser Session](/enterprise/how-to-trigger-an-external-scan/recording-browser-session) {% endcontent-ref %} ### Explore Manually When Debug Mode is enabled, **Explore manually** opens an interactive proxied crawler. **Crawl as** chooses one explicit logged-out or recorded-session context. Opening a crawler does not add another context to the assessment. {% content-ref url="/pages/Qe2U4mKd2ubu7USVan3H" %} [Manual Crawler](/enterprise/how-to-trigger-an-external-scan/manual-crawler) {% endcontent-ref %} ## 3. Configure Scan Settings Set the egress route and a request rate that the target can safely absorb. Use **Auto-calibrate** to send controlled test traffic and estimate a sustainable rate. For assessment intents, select the approved attack vectors. All available categories are selected by default for broad coverage. **Advanced** contains custom headers, browser behavior, trajectory scope, runtime controls, and optional concurrency limits.
External rate limit and attack-vector settings

Use a conservative request rate for production or fragile applications.

{% content-ref url="/pages/JqTFyGv6qHEq1MBlbEzs" %} [Configure Scan Settings for External Assessment](/enterprise/how-to-trigger-an-external-scan/configure-scan-settings-for-external-assessment) {% endcontent-ref %} ## 4. Choose Automation Choose one outcome: * run immediately; * schedule a one-time or recurring run. The schedule stores the scope and settings submitted with the run. Recreate it if credentials, browser sessions, target scope, or required agents later change. ## 5. Review and Start Review the intent, selected assets, authentication contexts, scan settings, automation, estimates, and validation messages. Use the **Edit** actions to correct any section. * **Start run** launches an immediate run. * **Schedule run** saves the configured schedule. Pentest Copilot blocks launch when required scope, verification, authentication, configuration, or worker checks fail. Fix the listed step rather than repeatedly submitting the same configuration. ## Monitor and Review * Use **Activity -> Activity** to monitor or cancel the run and inspect errors. * Use **External Assessment -> Statistics** for aggregate results. * Use **External Assessment -> Attack Paths** to triage validated findings. * Generate deliverables from **Reports**. ## Common Blocks | Problem | Check | | ---------------------------------------- | ------------------------------------------------------------------------------------------ | | Target cannot be selected or launched | Confirm it exists, is approved by whitelist rules, and is verified when required. | | Authenticated coverage is incomplete | Select at least one ready browser session for every intended role. | | Target blocks scanner traffic | Lower the rate, auto-calibrate, allowlist scanner IPs, or use approved residential egress. | | No actionable browser or API flows exist | Run Discovery, record/import a session, or use Manual Crawler in Debug Mode. | | A schedule uses old settings | Delete and recreate it with the current run configuration. | # Configure Scan Settings for External Assessment Reference for external Run Assessment scope and scan settings. Open **Modules -> External Assessment -> Run Assessment**. Authentication and starting URLs are configured per asset in **Scope**; traffic, vulnerability, browser, and runtime controls are configured in **Scan settings**. ## Scope Settings ### Authentication Coverage | Context | Behavior | | ------------------- | ----------------------------------------------------------------------- | | **Unauthenticated** | Crawls and tests without a recorded login state. | | **Authenticated** | Runs each selected browser session as an independent logged-in context. | | **Both** | Covers the public surface and every selected login state independently. | Authenticated coverage requires at least one selected browser session. Validate sessions before important scans and re-record sessions whose authentication has expired.
Authenticated and unauthenticated coverage controls

Select the contexts that should be included in the run.

### Starting URLs Starting URLs are optional and belong to a specific coverage context. * Enter an absolute path such as `/docs` or a full HTTP(S) URL on the selected asset. * Leave the field empty to begin at the domain root. * A browser session can have its own captured scan starting page. ### Browser Sessions Use one session per account or role that needs independent coverage. The scan uses the session context and tags to distinguish roles and evaluate privilege boundaries. Before selecting a session, confirm: * recording completed successfully; * authentication validation passed; * its egress is compatible with the scan egress; * the account remains authorized and active. ### Explore Manually Manual Crawler is available only in **Debug Mode**. **Crawl as** selects one explicit logged-out or recorded-session context. It does not change the assessment's selected authentication coverage. ## Rate Limit and Egress ### Egress * **Sandbox egress** uses the selected scanner location. * **Residential egress** uses the configured residential proxy location when available. Keep recording, validation, and assessment egress consistent for targets that restrict traffic by IP or country. A target that refuses a different egress can make a healthy browser session appear expired. ### Request Rate **Rate limit (req/min)** is the maximum request rate sent to the target. Lower it for production systems, strict WAFs, or fragile applications. Enable **No rate limit** only when the target owner has confirmed that maximum-speed traffic is safe. ### Auto-Calibrate **Auto-calibrate** sends controlled traffic to the first selected asset using the current egress and browser behavior. When calibration completes, review the completion message and the resulting recommended limit before continuing. Calibration can fail when the target is unreachable, blocks the chosen egress, or no compatible worker is available. ### Optional Concurrency Caps * **Max submodules** limits how many submodules may run concurrently for the target. * **Max concurrent jobs (agent)** limits jobs used on the selected agent. Leave either field empty to use the calibrated or agent-configured limit.
External request-rate, concurrency, calibration, and attack-vector controls

Rate and concurrency controls are independent.

## Attack Vectors Attack vectors select the vulnerability categories tested by an Assessment intent. All available categories are selected by default for broad coverage. Disable categories that are outside the approved engagement. The available list can include access-control, injection, client-side, server-side, request-handling, information-disclosure, and application-logic tests. ## Advanced Settings Expand **Advanced** only when the default behavior is unsuitable. ### Trajectory Scope Trajectories are discovered browser flows or API sequences. Search and select trajectories to narrow the assessment to specific workflows. If no useful trajectories exist, run Discovery or record/explore the missing flow first. ### Custom Headers Custom headers are sent with eligible external requests. Use them for approved routing, test identifiers, or target-required headers. Do not place secrets in headers unless the engagement requires them and their handling has been approved. ### Browser and Validation Controls Depending on deployment capabilities, advanced browser controls can include: * failing the run when a selected browser session is invalid; * skipping pre-run session validation; * residential browser traffic; * browser isolation or shared-browser behavior; * maximum crawler runs; * continuing when a baseline response resembles a not-found page. Keep the safer defaults unless you understand the effect on authentication accuracy, traffic, and isolation. ### Runtime Limits Runtime limits stop remaining work after the configured duration. They do not guarantee that every selected submodule finishes before the limit. ## Review The final **Review** step is the source of truth for the submitted run. Confirm: * intent and selected assets; * authentication contexts and browser-session readiness; * egress, rate, and concurrency; * attack vectors and trajectory scope; * advanced overrides; * schedule or immediate-start behavior; * estimates, warnings, and validation errors. Use **Start run** for an immediate run or **Schedule run** when Automation contains a schedule. # Recording Browser Session Record and manage an authenticated browser session. A browser session stores login actions and browser state so external assessments can test an authenticated account. Record separate sessions for roles whose permissions should be assessed independently. ## Open Browser Session Manager 1. Open **External Assessment -> Run Assessment**. 2. Choose an intent and continue to **Scope**. 3. Select the target asset and enable **Authenticated** coverage. 4. Select **Record new session**. Browser Session Manager shows recording, validation, and failure status for sessions associated with that target. ## 1. Describe the Account Choose an email identity when the login uses a monitored email OTP or magic link. Choose **None** for a customer-managed account, long-lived session, or inbox that Pentest Copilot should not poll. Provide: * **Session Context**: the account's role, permissions, plan, tenant, or other facts needed to distinguish it; * **Tags**: short labels such as `admin`, `read-only`, or `billing`. Good context is specific: “Workspace administrator who can manage users and reports” is more useful than “logged-in user.” ## 2. Choose Where the Browser Runs Choose sandbox or residential egress and the required location. Recording, validation, and assessment should use compatible egress. Sites that restrict traffic by IP or country can reject a valid session when later validation uses a different route. ## 3. Choose Where Recording Starts **Open recorder at** is optional. Enter a login URL when it is not easy to reach from the domain root. The scan starting page and authentication verification page are captured inside the recorder. After recording, review them under **Captured scan pages**.
Browser Session Manager egress and optional recorder start settings

Use the same egress for recording, validation, and scanning when the target restricts source location.

## 4. Record the Login Select **Start Recording** and wait for the proxied browser to become ready. 1. Navigate to the login page. 2. Select **Start Auth** immediately before the first authentication action. 3. Complete the login one step at a time. 4. After dynamic fields or screens appear, select **Refresh** so the recorder rescans the DOM and highlights the new actionable elements. 5. On a page that is visible only when logged in, select **Set Verify URL**. 6. Select **Stop Auth**. 7. Optionally open the page where authenticated scanning should begin and select **Set Starting URL**. 8. Select **Done** and wait for the recording to finish saving. ### What Refresh Does **Refresh** does not reload the website. It refreshes the recorder's element map and highlights. Use it after a login step changes the current page without a full navigation—for example, when a password or OTP field appears dynamically. ### Clipboard Limitation The proxied browser does not reliably share your local system clipboard. Type credentials in the proxied browser or use the recorder's supported input and authentication helpers. Do not assume that a normal local copy/paste action reached the remote browser. ## Authentication Helpers The **Auth Actions** menu supports: | Action | Use | | -------------------- | --------------------------------------------------------------------------------- | | **TOTP** | Generate a code from a supplied Base32 secret and fill the selected OTP field. | | **Email OTP** | Poll the selected email identity and fill the extracted code. | | **Email Magic Link** | Poll the selected identity and navigate to the extracted sign-in link. | | **Phone OTP** | Use the configured SMS flow for the account. | | **OCR Captcha** | Select the captcha image and destination input for supported image-text captchas. | {% content-ref url="/pages/TZ5SP2OUJviyjLgpvBqw" %} [Handling Captcha/Email/Mobile OTPs](/enterprise/how-to-trigger-an-external-scan/handling-captcha-email-mobile-otps) {% endcontent-ref %} ## Review and Validate After saving: 1. Review **Captured scan pages** and correct the scan or verification page if needed. 2. Confirm the verification expression identifies authenticated content rather than a public page. 3. Select **Validate Session**. 4. Use the session in an authenticated assessment only when validation is ready. {% content-ref url="/pages/qlsZUTSSIvcyvgbeitK1" %} [Validating Browser Sessions](/enterprise/how-to-trigger-an-external-scan/validating-browser-sessions) {% endcontent-ref %} ## Re-record or Delete * **Re-record** updates an existing session while retaining its identity for linked configurations. * **Delete** removes a session that is failed, obsolete, or no longer authorized. Check whether saved schedules still reference it. If recording fails, review the visible error, close any abandoned proxied browser, then re-record or delete the failed session before continuing. ## What Is Stored A session can include login actions, cookies, local/session/cache storage, IndexedDB, WebAuthn data, captured pages, authentication criteria, page hashes, email-identity metadata, context, and tags. Treat exported session JSON as sensitive authentication material. # Importing Browser Session Import an existing browser session JSON bundle. Use **Import Existing Session** when you already have a browser session JSON bundle from another target, workspace, or previous export. ### Import from JSON 1. Open **External Assessment -> Run Assessment** and continue to **Scope**. 2. Select the target asset, enable **Authenticated**, and click **Record new session** to open **Browser Session Manager**. 3. Select **Import Existing Session**. 4. Paste the browser session JSON or upload the JSON file. 5. Review or edit the session context, tags, browser actions, and authentication verification regex. 6. Select the email identity for this session. Its saved **Account & access notes** appear below the selector. Choose **None** when the imported session uses a customer-managed account or long-lived login. 7. Save the imported session. The imported session appears in the browser-session selector for that target. Validate it before using it for authenticated scans. Treat imported JSON as sensitive authentication material. {% content-ref url="/pages/qlsZUTSSIvcyvgbeitK1" %} [Validating Browser Sessions](/enterprise/how-to-trigger-an-external-scan/validating-browser-sessions) {% endcontent-ref %} ### What the JSON Contains A browser session JSON bundle can include: * recorded browser actions; * cookies and storage; * authentication verification URL and regex; * valid-session page hashes; * WebAuthn credentials; * email identity metadata; * session context and tags. ### Legacy Extension Exports Older browser-session extension exports can still be imported if you have the JSON output. You do not need to install the old Chrome extension to import a session into the current product flow. # Validating Browser Sessions Post creation of browser sessions validate them to ensure successful scans Browser session validation checks that a recorded session works before security scans. It verifies authentication, unauthenticated contrast, action replay, and parallel-tab behavior. ### Validation States Sessions have three states: 1. **Pending Validation (Yellow)** - Not yet validated. New sessions start here. 2. **Validated (Green)** - All checks passed. Ready for scans. 3. **Validation Failed (Red)** - At least one check failed. Fix issues before using. ### Validation Checks #### 1. Authenticated Check Checks whether the session authenticates correctly when loaded. * Loads the session cookies and storage. * Visits the authentication URL. * Compares the result to the expected authenticated page. Passed: Shows authenticated content (dashboard, profile, etc.) Failed: Shows login page or error (session expired/invalid) *** #### 2. Unauthenticated Check Checks whether the site shows the unauthenticated page when no session is present. * Visits the same URL without session data. * Compares the result to the expected unauthenticated page. Passed: Shows login page or "access denied" Failed: Shows authenticated content (security issue) *** #### 3. Replay Test Checks if the recorded browser actions can be replayed successfully. * Replays the recorded actions: clicks, typing, and navigation. * Compares the final page to the expected authenticated state. Passed: Actions complete and result in authenticated state Failed: Actions fail or don't reach authenticated state *** #### 4. Parallel Tab Testing Checks whether the application can keep three authenticated tabs active at the same time. * Opens three tabs with the authenticated session. * Reloads all tabs simultaneously. Passed: All tabs maintain the authenticated state after reloads Failed: At least one tab loses the authenticated state. *** ### How to Trigger Validation 1. Open **External Assessment -> Run Assessment**, continue to **Scope**, select the target asset, enable **Authenticated**, and click **Record new session**. 2. Select an existing session from the dropdown. The session loads in preview mode. 3. (Optional) Review or edit session details, context, tags, or browser actions. 4. Click **Validate Session** and wait for the validation results. Use the VNC URL to watch the validation run when needed. 5. Review results when they appear. Green borders mean passed and red borders mean failed. Click the eye icon to view screenshots. 6. Re-record or delete a failed session when it is no longer useful. Check saved schedules before deleting a session they may reference. {% hint style="warning" %} If any validation check fails, treat the session as unsafe for authenticated scans until it is fixed or re-recorded. Confirm all four checks pass before running an authenticated scan. {% endhint %} #### A few things to keep in mind 1. During recording make sure bounding boxes are completely loaded before doing any action (for eg: click/fill etc..) - if bounding boxes are not visible hit "Refresh" button in the actions toolbar. 2. Ensure the actions recorded do not have temporary tokens, one-time authentication data - this might lead to validation failure during replay 3. If the validation check fails the browser session manager will prompt what might have went wrong as a warning - you can use this information to re-record the browser session. # Handling Captcha/Email/Mobile OTPs Use the recorder's **Auth Actions** menu when a login requires an OTP, magic link, authenticator code, or supported image CAPTCHA. ## Choose the Correct Identity Before recording, select the email identity assigned to the account in Browser Session Manager. Later scans poll only that exact inbox for email OTPs and magic links. Do not invent plus-address suffixes or use another identity unless it is explicitly listed for the workspace. Choose **None** when the account uses a customer-managed inbox or a long-lived session that Pentest Copilot should not poll. ## Auth Actions | Challenge | Action | | --------------------------------- | ------------------------------------------------------------------------------------------------ | | Email code | Select **Email OTP**, then click the destination input when prompted. | | Email sign-in link | Select **Email Magic Link**; the recorder polls the selected inbox and opens the extracted link. | | SMS code | Select **Phone OTP** and follow the recorder status instructions. | | Authenticator app | Select **TOTP**, provide the Base32 secret, then click the OTP input when prompted. | | Image containing text | Select **OCR Captcha**, then select the image and destination input in the requested order. | | reCAPTCHA, hCaptcha, or Turnstile | Wait for the configured solver. If it does not complete, follow the failure guidance below. | Wait for the recorder status to return to ready before continuing. ## TOTP Provide the Base32 secret shown during authenticator enrollment, not a currently displayed six-digit code. The secret is stored with the browser session so later authentication replay can generate a current code. Treat exported browser-session data as sensitive because it can contain the TOTP secret. ## OCR CAPTCHA 1. Select **Auth Actions -> OCR Captcha**. 2. When prompted, click the image containing the characters. 3. When prompted, click the input where the answer belongs. 4. Wait for the recorder to solve and fill the value. Do not manually fill the same input while the OCR action is running. If the answer is wrong, request a new CAPTCHA and repeat the action. ## When a Challenge Fails * Confirm the correct email identity or phone workflow was selected before recording. * Use **Refresh** after the target dynamically adds the OTP or CAPTCHA input so it becomes highlighted. * Confirm the code or link belongs to the current login attempt and has not expired. * Retry a fresh CAPTCHA rather than repeatedly submitting an old challenge. * If the target blocks automated solving, complete the challenge manually when authorized and note that replay may still require support. * Re-record the session if authentication actions or verification pages were captured incorrectly. For engagement-specific identity provisioning or targets that allowlist particular email domains or phone numbers, contact Bugbase support before recording. # Manual Crawler Explore an external target interactively in Debug Mode. Manual Crawler opens a proxied browser so an operator can capture important pages and user flows that automated discovery missed. {% hint style="warning" %} Manual Crawler is a Debug Mode capability. It is hidden or disabled on deployments and workspaces where Debug Mode is not enabled. {% endhint %} ## Start a Crawler 1. Open **External Assessment -> Run Assessment**. 2. Choose an intent that includes the target and continue to **Scope**. 3. Select and configure the asset. 4. Under **Explore manually**, choose **Crawl as**: * **Unauthenticated** starts without a login state; * a named browser session reuses that recorded account. 5. Select **Open logged-out crawler** or **Open session crawler**. The selected crawl context is independent of the assessment's authentication coverage. Opening a crawler does not add another context to the run. ## Use the Proxied Browser Wait for the status indicator to show that the browser is ready before each action. | Control | Use | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Start Recording** | Begin a trajectory from the current page. | | **Refresh** | Rescan the current DOM and reapply actionable-element highlights after dynamic content changes. It does not perform a normal browser reload. | | **Reset** | Discard the in-progress trajectory and return to its starting point. | | **Done** | Save captured trajectories and end the crawler. | | **Abort** | Stop without saving the current in-progress trajectory. | Use **Refresh** when a click, form step, or single-page application navigation reveals new controls that are not highlighted. Normal page navigation automatically refreshes highlights when it completes. Keep the proxied browser open until the UI confirms that the trajectory was saved. Cancel the crawler from Pentest Copilot if the browser becomes unusable. # How to Trigger a Code Assessment Connect GitHub repositories and run a Code Assessment. Code Assessment reviews source available through the Pentest Copilot GitHub App. It does not include unpushed local changes. ## 1. Connect GitHub Open **Settings -> Integrations -> GitHub** and install or connect the Pentest Copilot GitHub App. During installation: * choose the account or organization that owns the repositories; * grant access to all repositories or the required selected repositories; * return to Pentest Copilot and confirm the connection. {% content-ref url="/pages/cSYGK9VOV5u61rz8tVT0" %} [Configure GitHub for Code Assessment](/enterprise/how-to-trigger-a-code-assessment/configure-github-for-code-assessment) {% endcontent-ref %} ## 2. Select Repositories and Targets Open **Modules -> Code Assessment -> Run Assessment**. Select one or more repositories. Each selected row has its own **Assessment target** dropdown: * start typing to rank live branches, open pull requests, and recent commits; * select the default branch when no special target is needed; * enter an exact branch, tag, `#PR`, PR number, or commit SHA and press Enter when it is not in the suggestions. If live GitHub targets cannot be loaded, exact target entry remains available.
Code Assessment repository target dropdown with live branches, pull requests, and commits

Assessment targets are selected per repository.

{% hint style="warning" %} The selected branch, PR, tag, or commit must exist in GitHub. Local unpushed changes are not scanned. {% endhint %} ## 3. Configure Scan Settings Choose the checks required for the run, including source-code paths, dependency risk, secrets, authorization/business logic, and AI inventory where available. {% content-ref url="/pages/jCO3SrYhFV3I1FvxB9FK" %} [Configure Scan Settings for Code Assessment](/enterprise/how-to-trigger-a-code-assessment/configure-scan-settings-for-code-assessment) {% endcontent-ref %} ## 4. Configure Automation Automation is saved per selected repository. * **Allow manual and scheduled branch runs** permits runs started from this wizard and schedules. * **Run on future pull requests** assesses the latest PR commit when supported GitHub events arrive. * **Run on future push** assesses pushed commits that match the optional branch regular expressions. You can run now, schedule a run, or save automation without starting a branch run. ## 5. Review and Submit Confirm repositories, exact assessment targets, enabled checks, auto-fix behavior, and automation. * **Start run** starts the selected branch/PR/commit assessment. * **Schedule run** creates the configured schedule. * **Save automation** stores repository event rules without starting a run. ## Monitor and Review * **Activity -> Activity** shows pending, running, completed, failed, and cancelled runs. * **Code Assessment -> Statistics** summarizes findings. * **Code Assessment -> Attack Paths** contains validated findings and remediation. * **Code Assessment -> SBOM** contains inventory verification and SPDX, CycloneDX, and AI-BOM exports. ## Common Blocks | Problem | Check | | ----------------------------- | --------------------------------------------------------------------------------------- | | Repository is missing | Confirm it is included in the GitHub App installation. | | Live targets cannot be loaded | Refresh the dropdown or enter the exact branch, tag, PR, or SHA. | | PR scan did not run | Confirm PR automation was saved before the event and the App can access the repository. | | Push scan did not run | Confirm push automation is enabled and the branch matches the configured regex. | | Auto-fix did not create a PR | Confirm the finding is validated, fixable, and the repository uses Auto PR mode. | # Configure GitHub for Code Assessment Connect the Pentest Copilot GitHub App, choose repositories, and enable pull request or push automation for Code Assessment. Code Assessment connects to GitHub through the Pentest Copilot GitHub App. After the GitHub App is installed, Pentest Copilot can read selected repositories, create check results, comment on pull requests, create issues, and open fix pull requests when you enable those workflows. ## Before You Start You need: * access to Pentest Copilot with permission to manage integrations or run Code Assessment; * GitHub permission to install a GitHub App on the target organization or account; * approval for the repositories that will be scanned; * for automatic pull request or push scans, the repository must be connected in Pentest Copilot and have scan settings saved. {% hint style="warning" %} Installing the GitHub App alone does not automatically scan every repository. Automatic scans only start for repositories that you connect and configure in Pentest Copilot. {% endhint %} ## Connect the GitHub App 1. In Pentest Copilot, open **Settings -> Integrations -> GitHub** or **Modules -> Code Assessment**. 2. Click **Connect GitHub**. 3. GitHub opens the Pentest Copilot GitHub App installation page. 4. Choose the GitHub organization or account. 5. Select **All repositories** or **Only select repositories**. 6. Approve the installation. 7. Return to Pentest Copilot and confirm the integration shows as connected. If a repository is missing, open the GitHub App installation settings in GitHub and add that repository to the App's repository access list. ## Use the Right Pentest Copilot Account Always start the installation from **Connect GitHub** inside the Pentest Copilot account where you want the repositories to appear. {% hint style="info" %} If your organization uses more than one Pentest Copilot account or workspace, open the correct one before connecting GitHub. {% endhint %} ## Connect Repositories in Pentest Copilot After the App is installed, open **Settings -> Integrations -> GitHub** or **Modules -> Code Assessment**. You can configure repositories in two ways: | Repository setup | What it does | Use when | | ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Standalone Code Assessment repository** | Adds the repository as a Code Assessment target. | You want source-code scans, scheduled scans, pull request scans, push scans, SBOM, AI-BOM, and code findings. | | **Repository connected to a domain** | Links a repository to an external application domain. | You want external findings on that domain to be patchable against the connected source repositories. | You can use both. A repository can be a direct Code Assessment target and also be connected to a domain. ## Enable Automatic Scans Automatic scans are configured per repository from **Modules -> Code Assessment -> Scan settings**. | Trigger | Default | What is scanned | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | **Pull request** | On | The latest commit on the pull request. | | **Push** | Off | The commit that was pushed, only when push scans are enabled and the branch matches the repository settings. | Pull request scans run when a pull request is opened, reopened, marked ready for review, or updated with new commits. Push scans ignore tags and branch deletions. With no branch filter, push scans run only on the repository default branch. With branch filters, the pushed branch must match one of the saved regular expressions. Examples: | Branch filter | Matches | | ------------- | -------------------------------------------------------------- | | `main` | Only `main`. | | `release/.*` | Branches such as `release/2026.07` and `release/hotfix`. | | `feature/.+` | Feature branches with at least one character after `feature/`. | ## Common Blocks | Block | What to check | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | GitHub redirects to the App settings page instead of Pentest Copilot | Start the install again from **Connect GitHub** in Pentest Copilot. If it still does not return to Pentest Copilot, contact BugBase support. | | Repository does not appear | Confirm the App installation has access to that repository. | | Pull request event did not start a scan | Confirm the repository is connected in Pentest Copilot and **Scan every pull request** is enabled for that repository. | | Push event did not start a scan | Confirm **Scan pushes** is enabled and the pushed branch matches the saved branch filters. | | Repositories appear in the wrong Pentest Copilot account | Disconnect GitHub and reconnect it from the account where you want to run Code Assessment. | # Configure Scan Settings for Code Assessment Configure Code Assessment checks, automation, and remediation behavior. Open **Modules -> Code Assessment -> Run Assessment**. Settings apply to the repositories selected in Scope. ## Checks | Check | Outcome | | ------------------------------------ | ----------------------------------------------------------------------------------- | | **Vulnerable code paths** | Reviews paths from user-controlled input to security-sensitive operations. | | **Open-source dependency risk** | Reviews manifests and lockfiles for affected packages and upgrade guidance. | | **Leaked secrets and credentials** | Detects committed tokens, keys, credentials, and similar sensitive material. | | **Business logic and authorization** | Reviews tenant boundaries, roles, approvals, IDOR, and unsafe state transitions. | | **AI inventory** | Maps models, providers, prompt surfaces, and inference locations for AI-BOM output. | Enable the checks required by the review. A first baseline normally uses all available checks. ## Assessment Targets Targets are chosen per repository in Scope. | Target | Result | | -------------- | ----------------------------------------------------- | | Default branch | Scans the repository default branch shown in the row. | | Branch or tag | Scans the exact Git reference entered or selected. | | Pull request | Scans the latest commit for the selected PR. | | Commit SHA | Scans that exact commit. | The dropdown ranks live GitHub suggestions while you type. Exact branch, tag, PR, or SHA entry remains available when suggestions fail to load. ## Automation | Option | Behavior | | ------------------------------------------ | ---------------------------------------------------------------------- | | **Allow manual and scheduled branch runs** | Allows this wizard and saved schedules to start branch-based runs. | | **Run on future pull requests** | Starts a scan when a PR is opened, reopened, marked ready, or updated. | | **Run on future push** | Starts a scan for pushed commits matching the optional branch regexes. | | **Branch regexes** | Narrows push-triggered runs to matching full branch names. | Use regular expressions such as `main`, `release/.*`, or `feature/.+`. With no push filter, default-branch behavior depends on the repository automation configuration shown in Review. ## Auto-fix | Mode | Behavior | | ----------- | -------------------------------------------------------------------------------------------------- | | **Off** | Findings include evidence and remediation guidance but no generated patch. | | **Suggest** | Marks validated findings that are suitable for an operator-requested patch. | | **Auto PR** | Creates a patch branch and pull request for validated findings that are safe to fix automatically. | Auto-fix does not guarantee a patch for every finding. ## Submit Behavior The final button depends on Automation: * **Start run** begins the selected target assessment. * **Schedule run** stores a one-time or recurring run. * **Save automation** saves PR and push rules without starting a branch run. ## SBOM and AI-BOM After a completed run, open **Code Assessment -> SBOM** to review inventory verification and download: * SPDX 2.3 JSON; * CycloneDX 1.6 JSON; * AI-BOM JSON. ## Before Enabling Automation Confirm the GitHub App has access to the intended repositories, branch expressions match real branch names, repository owners expect comments or pull requests, and auto-fix matches the team's change-management process. # How to Trigger an Internal Scan Configure and start an internal discovery or assessment run. Internal assessment runs through an agent deployed inside the approved environment. The agent supplies reachable subnet inventory and executes work from inside that network. {% hint style="warning" %} Assessment intents can execute exploits, change AD/ADCS or host state, capture credentials, deploy callbacks, forge tickets, or copy data. Confirm authorization, exclusions, and cleanup ownership before launch. {% endhint %} ## Before You Start 1. Install the agent from **Settings -> Agent** or **Download Agent**. 2. Place it on a host that can route to the approved networks. 3. Confirm it is connected and reports the expected subnets and interfaces. 4. Agree which exploit families, relay/intercept behavior, and state-changing actions are allowed. {% content-ref url="/pages/qJVQdMWQN3SOOKDv02QD" %} [Download Agent](/enterprise/download-agent) {% endcontent-ref %} Cloud control-plane work also uses Internal Assessment, but requires an agent on a supported cloud VM with an attached workload identity. {% content-ref url="/pages/cycdJfiZOF1JvOhhmyH7" %} [Run a Cloud Assessment](/enterprise/how-to-trigger-a-cloud-assessment) {% endcontent-ref %} ## 1. Choose the Intent Open **Modules -> Internal Assessment -> Run Assessment**. | Intent | Behavior | | -------------------------- | ----------------------------------------------------------------------------------------------- | | **Discovery** | Enumerates reachable systems, accounts, services, and trust relationships without exploitation. | | **Assessment** | Tests inventory already discovered for the selected environment. | | **Discovery + Assessment** | Discovers the environment first, then tests the systems and paths found. |
Internal Run Assessment intent choices

Use Discovery plus Assessment when inventory should be refreshed before testing.

## 2. Select the Agent and Scope Choose the connected execution agent. Only subnets reported as reachable by that agent are shown. Select one or more top-level subnets. To narrow execution inside a subnet, enter a partial target as: * a single IP, such as `10.10.10.25`; * an IP range, such as `10.10.10.20-10.10.10.50`; * a CIDR, such as `10.10.10.0/24`. Partial targets must remain inside their top-level subnet. They narrow the run; they do not create a new root subnet. For an Assessment-only intent, select previously discovered internal or cloud targets presented by the wizard. ## 3. Configure Scan Settings ### Discovery Controls Cloud collection uses the selected agent's attached workload identity when one is present. * **AWS resource name prefixes** are optional. Add them only when AWS collection is in scope and the engagement needs to restrict resources by literal name prefix. * Azure, GCP, local network, Active Directory, and hybrid environments do not require an AWS prefix. * Runtime fields set optional discovery and post-discovery assessment limits; `0` disables the corresponding limit. ### Attack Selection Enable only exploit families approved for the engagement. Defaults can include credential, configuration, privilege-escalation, lateral-movement, code-execution, directory-service, and cloud categories. The final review shows how many families are enabled. Recheck state-changing categories even if they were selected by default. ### PCE Intercept/Inveigh Enable intercept/relay behavior only when explicitly approved. Select at least one valid interface on the chosen agent; launch is blocked when intercept is enabled without an interface. ### RCE Safeguards Use the available skip controls when repeated command execution is unnecessary after the graph already proves that a host or user is compromised. ### Entity Exclusions Exclude discovered hosts, users, groups, services, or other entities that must not be tested. Refresh the entity list if discovery recently added inventory. {% content-ref url="/pages/Wo8uaAQGOpoDSX3mEaRZ" %} [Internal Assessment Destructive Actions](/enterprise/how-to-trigger-an-internal-scan/internal-assessment-destructive-actions) {% endcontent-ref %} ## 4. Choose Automation Run immediately or configure a one-time or recurring schedule. Scheduled runs store the selected agent, scope, exploit choices, exclusions, interfaces, safeguards, and runtime settings submitted at creation time. Recreate a schedule when its agent, scope, credentials, or authorization changes. ## 5. Review and Start Confirm: * intent, agent, and selected subnets or discovered targets; * partial targets; * enabled exploit families and destructive-action warnings; * PCE Intercept/Inveigh and selected interfaces; * RCE safeguards and excluded entities; * runtime limits, estimates, and schedule. Choose **Start run** or **Schedule run**. Validation messages identify the step that must be corrected before launch. ## Monitor and Triage * **Activity -> Activity** shows execution status and cancellation controls. * **Activity -> Attack Logs** contains detailed operational logs. * **Internal Assessment -> Statistics** summarizes results. * **Internal Assessment -> Attack Paths** contains validated findings. * **Reports** generates assessment deliverables. ## Common Blocks | Problem | Check | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | No agent can be selected | Confirm a compatible internal agent is connected and assigned to the workspace. | | Expected subnet is missing | Confirm the selected agent reports and can route to that subnet. | | Partial target is rejected | Keep the IP, range, or CIDR inside its listed top-level subnet. | | Intercept is enabled but launch is blocked | Select at least one interface on the execution agent. | | AWS prefix validation appears for a non-AWS run | Clear AWS-specific scope; prefixes are optional and should not block local, Azure, GCP, or hybrid runs. | # Internal Assessment Destructive Actions Understand which Internal Assessment exploit categories can make persistent, destructive, or hard-to-revert changes. Internal Assessment can simulate real adversary activity inside Active Directory and connected hosts. Some exploit categories only validate exposure or collect evidence. Others can change account state, directory permissions, certificate services, delegation settings, host configuration, or credential material. Pentest Copilot highlights these selections in the final configuration review. The product warning is intentionally short so operators can make a fast decision before launching the assessment. This page explains the impact behind those warnings in plain language. ## Before enabling high-impact exploit categories Before running an internal assessment with destructive or hard-to-revert categories enabled: * Confirm the engagement allows active exploitation, not only enumeration. * Confirm who owns rollback for Active Directory, certificate services, GPOs, delegation settings, and endpoint cleanup. * Snapshot lab or staging domains where possible. * Keep domain controller recovery procedures ready before enabling domain controller authentication-bypass testing. * Plan credential rotation for any password, hash, Kerberos ticket, trust key, KRBTGT material, or LAPS password recovered during the run. * Disable any exploit category that is outside the approved engagement scope. ## Critical Active Directory and certificate-service changes These categories can directly change Active Directory, Active Directory Certificate Services, or domain controller state. ### ACL Privilege Escalation This category abuses dangerous permissions that a user or group has over another Active Directory object. Examples include rights to reset a password, add a member to a group, write to an object, change object ownership, or modify object permissions. **What Pentest Copilot may do** * Reset an AD user's password to prove the account can be taken over. * Add a user or computer to an AD group when group-control permissions allow it. * Grant additional control over an AD object by changing its permissions. * Change the owner of an AD object and then use that ownership to gain more control. * Add certificate or key-based logon material to an account to recover credential material. * Abuse GPO control to create a local administrator account on affected machines. * Read LAPS-managed local administrator passwords if the discovered permissions allow it. **What can remain changed** * User passwords. * Group membership. * Object permissions and owners. * GPO-controlled local administrator changes. * Certificate or key-based account login material. * Recovered local administrator credentials. **Cleanup expectations** * Restore changed passwords. * Remove added group members. * Revert object owner and permission changes. * Remove GPO artifacts and any local administrator accounts created through GPO abuse. * Review affected accounts for unexpected certificate or key-based login material. * Rotate any recovered credentials or LAPS passwords. ### Resource-Based Constrained Delegation This category abuses delegation settings that allow one computer account to impersonate users to another computer. In practice, this can let an attacker act as an administrator to a target host. **What Pentest Copilot may do** * Create a controlled computer account in Active Directory. * Change the target computer's delegation configuration so the controlled account can impersonate users to that target. * Request Kerberos tickets through the new delegation path. * Use those tickets for follow-on access to the target system. **What can remain changed** * A newly created computer account. * Delegation settings on the target computer object. * Kerberos tickets or credential material generated through the delegation path. **Cleanup expectations** * Delete the controlled computer account created during the assessment. * Clear the target computer's resource-based delegation setting. * Review ticket use from the delegated identity. ### Domain Controller Authentication Bypass This category validates high-impact domain controller authentication-bypass conditions, such as ZeroLogon-style abuse. A successful exploit can take over a domain controller and expose domain credential material. **What Pentest Copilot may do** * Attempt the authentication bypass against a domain controller. * Reset the domain controller machine-account password as part of the takeover path. * Collect password hashes or other credential material from the domain controller after takeover. **What can remain changed** * The domain controller machine-account password. * Domain credential material exposed during collection. * Domain controller health if the machine-account password is not restored correctly. **Cleanup expectations** * Restore the domain controller machine-account password immediately. * Verify domain controller health, trust, replication, and authentication behavior. * Treat any recovered domain credential material as compromised. ### ADCS Certificate Abuse This category abuses unsafe Active Directory Certificate Services configuration. Certificate abuse can allow privileged impersonation even when the original password is unknown. **What Pentest Copilot may do** * Request certificates that allow impersonation of privileged users. * Forge or use certificates to recover credential material. * Temporarily change a certificate template when the attack path requires it. * Modify certificate authority permissions or enable a dangerous template when the attack path requires it. * Change account attributes or certificate login material for certificate-based impersonation. * Relay authentication to certificate enrollment services. * Access certificate authority material when administrative access to the certificate authority is available. **What can remain changed** * Certificate template permissions or settings. * Certificate authority officer or enrollment settings. * Issued or failed certificate requests. * Account attributes used for certificate mapping. * Certificate or private-key artifacts created during exploitation. * Credential material recovered through certificate authentication. **Cleanup expectations** * Review and revert certificate authority permission changes. * Review enabled templates and template permissions. * Review issued and failed certificate requests. * Remove unintended account attribute or certificate-mapping changes. * Revoke certificates where appropriate. * Rotate credentials recovered through certificate authentication. ## High-impact host, credential, and ticket actions These categories may not always write directly to Active Directory, but they can deploy implants, extract reusable credentials, forge tickets, or move laterally. ### Remote Code Execution This category uses valid access or a confirmed vulnerability to run commands on a reachable host. **What Pentest Copilot may do** * Run commands over Windows or Linux administration protocols. * Run commands through a database server when database-level command execution is available. * Deploy and start a callback agent or implant. * Mark the host as compromised and run follow-on post-compromise checks. * Enable operating-system command execution through a database feature when that is part of the path. **What can remain changed** * Dropped payloads, callback agents, services, scheduled tasks, or temporary files. * Host configuration changed to enable command execution. * Logs and security telemetry generated by command execution. **Cleanup expectations** * Remove deployed agents, services, scheduled tasks, and temporary payloads. * Disable database command-execution features if they were enabled. * Review host logs and endpoint state. ### Local Privilege Escalation This category attempts to turn an already reached account into a more privileged account on the same host. **What Pentest Copilot may do** * Run local privilege-escalation techniques on a reached host. * Start an elevated callback agent if exploitation succeeds. * Continue post-compromise collection from the elevated context. **What can remain changed** * Elevated callback artifacts. * Temporary exploit files or process artifacts. * Host logs and security telemetry. **Cleanup expectations** * Remove elevated callback artifacts. * Validate the host state after exploitation. * Patch or mitigate the local escalation condition. ### Credential Exposure and Reuse This category uses discovered passwords, hashes, or tickets to prove what access they provide. **What Pentest Copilot may do** * Authenticate with discovered passwords, hashes, or Kerberos tickets. * Crack exposed Kerberos material when roasting paths produce hashes. * Use credentialed access for remote execution when the target allows it. * Continue post-compromise collection on newly reached hosts. **What can remain changed** * Reusable credential material in assessment artifacts. * Callback artifacts created by follow-on remote execution. * Authentication logs across affected services and hosts. **Cleanup expectations** * Rotate exposed passwords and hashes. * Invalidate or expire exposed Kerberos tickets where possible. * Remove callback artifacts created through follow-on remote execution. ### Domain Trust Abuse This category abuses trust relationships between Active Directory domains. A successful path can enable cross-domain access. **What Pentest Copilot may do** * Extract trust material from a domain. * Create tickets that cross a domain trust boundary. * Use trusted-domain access for follow-on actions. **What can remain changed** * Trust keys or other trust material exposed in assessment artifacts. * Reusable Kerberos tickets. * Cross-domain authentication traces. **Cleanup expectations** * Treat extracted trust material as compromised. * Rotate trust material according to domain recovery procedures. * Review cross-domain ticket use. ### Golden Ticket Forging This category uses domain Kerberos signing material to create a forged domain ticket. **What Pentest Copilot may do** * Use KRBTGT hash material and the domain SID to forge an administrator ticket. * Store the forged ticket for pass-the-ticket follow-on actions. **What can remain changed** * Reusable forged ticket material. * Domain-wide Kerberos exposure until the underlying KRBTGT material is rotated. **Cleanup expectations** * Rotate KRBTGT according to the organization's domain recovery procedure. * Review Kerberos logs for forged ticket use. ### Constrained Delegation Abuse This category abuses constrained delegation configuration to impersonate users to specific services. **What Pentest Copilot may do** * Request or extract service tickets for impersonation. * Use delegated access to act as a privileged user to a target service. * Store ticket material for follow-on actions. **What can remain changed** * Reusable service ticket material in assessment artifacts. * Authentication traces from impersonated access. **Cleanup expectations** * Invalidate exposed tickets where possible. * Review delegated service account usage. * Tighten constrained delegation configuration if it is overly broad. ### Unconstrained Delegation Ticket Theft This category targets hosts configured with unconstrained delegation. Such hosts can hold delegated Kerberos tickets in memory. **What Pentest Copilot may do** * Trigger authentication to a delegated host. * Dump Kerberos tickets from memory on that host. * Store captured tickets for pass-the-ticket follow-on actions. **What can remain changed** * Captured Kerberos ticket material. * Temporary ticket dump files or archives. * Authentication traces from coercion and ticket use. **Cleanup expectations** * Invalidate exposed tickets where possible. * Remove temporary ticket dump artifacts from the host. * Review and reduce unconstrained delegation assignments. ### Lateral Movement This category uses confirmed access to move from one internal system to another. **What Pentest Copilot may do** * Authenticate to additional reachable hosts. * Run remote execution or database command-execution paths on services with supported execution methods. * Expand post-compromise collection to newly reached systems. **What can remain changed** * Callback agents, temporary payloads, or service changes on reached hosts. * Authentication and execution logs across multiple systems. * Reusable credentials or tickets created during the movement path. **Cleanup expectations** * Review all reached hosts for callback artifacts. * Rotate credentials used for movement. * Validate host compromise state and service changes. ## Sensitive collection paths These categories are less likely to modify Active Directory objects, but they can collect sensitive data that requires careful handling after the assessment. ### Credential Disclosure This category collects or cracks credential material that was exposed by another finding. **What Pentest Copilot may do** * Crack or parse exposed credential material. * Store recovered secrets in assessment artifacts. * Use recovered credentials for follow-on checks if those categories are enabled. **Cleanup expectations** * Rotate any recovered credentials. * Handle exported credential artifacts as sensitive data. ### LAPS Password Access This category reads local administrator passwords managed through Windows LAPS when directory permissions expose them. **What Pentest Copilot may do** * Query directory attributes that expose LAPS-managed local administrator passwords. * Store recovered local administrator credentials for follow-on checks. **Cleanup expectations** * Rotate exposed local administrator passwords. * Review which users or groups can read LAPS password attributes. ### SMB Share Data Collection This category reviews accessible Windows file shares for sensitive files. **What Pentest Copilot may do** * List files on accessible SMB shares. * Download selected files to assessment storage. * Analyze copied files for secrets or sensitive content. **Cleanup expectations** * Treat copied files and extracted secrets as sensitive assessment artifacts. * Remove or archive artifacts according to the engagement data-handling policy. ### FTP and Information Disclosure Collection This category reviews accessible FTP or similar exposed file services for sensitive files. **What Pentest Copilot may do** * Enumerate exposed files or records from reachable services. * Copy selected content into assessment artifacts for review. **Cleanup expectations** * Treat copied data as sensitive assessment output. * Rotate credentials if collected content exposes secrets. ## How to reduce risk from the UI In the final configuration review, disable any exploit category that is outside the engagement's approved scope. For a lower-risk internal run: * Disable ACL privilege escalation, resource-based constrained delegation, domain controller authentication bypass, and ADCS certificate abuse unless AD or certificate-service writes are approved. * Disable remote code execution, local privilege escalation, and lateral movement unless host compromise and callback deployment are approved. * Disable credential, ticket, delegation, and trust-abuse categories unless credential collection, cracking, and reuse are approved. * Keep discovery and enumeration enabled when you only need network and graph visibility. # Run a Cloud Assessment Set up and run an AWS, Azure, or Google Cloud assessment. Cloud assessment uses **Internal Assessment -> Run Assessment**. An agent running on a cloud VM uses that VM's attached IAM role, managed identity, or service account. Do not enter long-lived cloud credentials into Pentest Copilot. {% hint style="warning" %} Active cloud tests can read sensitive data or change IAM, workloads, networks, logging, storage, keys, and recovery state. Use only approved identities, categories, scope, and test windows. {% endhint %} ## Before You Start Confirm: * the approved AWS account, Azure subscription/resource group, or GCP project; * a supported VM with the Pentest Copilot agent and attached workload identity; * outbound connectivity to Pentest Copilot and provider APIs; * discovery permissions on the attached identity; * ownership for temporary permissions, rollback, cleanup, and credential rotation. {% content-ref url="/pages/ZeohD2bm8TpS8XBNG2W9" %} [Cloud Assessment Prerequisites](/enterprise/how-to-trigger-a-cloud-assessment/configure-a-cloud-agent) {% endcontent-ref %} ## 1. Set Up the Agent Install the agent from **Settings -> Agent** on the approved cloud VM. Confirm that it connects and that native instance metadata is reachable from the agent process. The agent can connect without cloud read access, but provider discovery will be partial or unavailable until the attached identity has the required permissions. {% content-ref url="/pages/74xr08DgNEibdsc9F6Z2" %} [Set Up the Cloud Agent](/enterprise/how-to-trigger-a-cloud-assessment/provider-runbooks) {% endcontent-ref %} ## 2. Run Discovery Open **Modules -> Internal Assessment -> Run Assessment** and choose **Discovery** for an inventory-only run or **Discovery + Assessment** when active testing is already approved. 1. Select the cloud-hosted agent. 2. Select the subnet reported by that agent. 3. In Scan settings, add provider-specific scope only when applicable. 4. Review the workload identity and discovery runtime. 5. Start or schedule the run. Provider and account scope are detected from the VM identity. AWS resource-name prefixes are optional AWS-only restrictions; they are not required for Azure, GCP, local, or hybrid runs. When discovery completes, the resulting cloud scope becomes available to Assessment-only runs. {% content-ref url="/pages/jWUTr1QcyhW2QxWFXCHw" %} [Discovery Coverage](/enterprise/cloud-assessment-reference/cloud-discovery-coverage) {% endcontent-ref %} ## 3. Configure Active Assessment Choose **Assessment** to test a previously discovered cloud scope, or continue through a **Discovery + Assessment** run. 1. Select the discovered cloud target and connected cloud agent. 2. Disable every test category that is outside the authorization. 3. Enable retest, regional-monitoring, rollback, or RCE controls only when the engagement requires them. 4. Review temporary provider permissions and stop conditions. {% content-ref url="/pages/CfF0dPY4Kmmw9SWVKpdT" %} [Configure the Assessment](/enterprise/how-to-trigger-a-cloud-assessment/configure-cloud-assessment) {% endcontent-ref %} ## 4. Review and Start Confirm the provider scope, attached identity, agent, categories, rollback choices, runtime, and schedule. Then choose **Start run** or **Schedule run**. Monitor progress under **Activity -> Activity**. Completed findings appear under **Internal Assessment -> Attack Paths** and in the Exploit Graph. ## 5. Finish Safely After the run: 1. Confirm assessment and supported rollback work has stopped. 2. Remove temporary active permissions. 3. Complete required manual cleanup and credential rotation. 4. Preserve provider audit evidence. 5. Review findings and generate reports. {% content-ref url="/pages/9hB3HBinyL74mFNggXKn" %} [Safety and Cleanup](/enterprise/cloud-assessment-reference/cloud-assessment-safety-and-cleanup) {% endcontent-ref %} For provider permissions and inventory details, see [Cloud Assessment Reference](/enterprise/cloud-assessment-reference). # Cloud Assessment Prerequisites Confirm the cloud scope, VM, identity, network access, and operational ownership required for an assessment. ## Approved Scope Before deployment, confirm: * the AWS account, Azure subscription and resource group, or Google Cloud project; * the assessment window and permitted test categories; * excluded resources or operations; * the owner who can stop the assessment; * the owner of provider permissions and cleanup. ## Supported Agent Host The agent must run on provider compute and use the identity attached to that VM. | Provider | Agent host | Attached identity | Discovery boundary | | ------------ | ----------------- | ------------------------------------------------- | ------------------------------------------------------------------ | | AWS | EC2 instance | IAM role through an instance profile | Detected account, VM region, and configured resource-name prefixes | | Azure | Azure VM | System-assigned or user-assigned managed identity | Detected subscription and VM resource group | | Google Cloud | Compute Engine VM | Service account | Detected project | Static access keys, local CLI profiles, service-account key files, and redirected metadata endpoints are not used. ## VM Requirements Use an existing Windows or Linux VM or provision one that meets the requirements in [Download Agent](/enterprise/download-agent). An existing VM is supported when its operational use allows the agent to run during the assessment. Confirm that: * the VM is inside the approved cloud boundary; * native instance metadata is reachable; * outbound HTTPS reaches Pentest Copilot and required provider APIs; * the host clock is synchronized; * endpoint protection allows the documented agent files and processes. Cloud discovery and active cloud tests do not require a browser or interactive desktop session. ## Permission Plan The agent can install and connect without provider read or administrator access. For cloud assessment, plan: 1. **Discovery permissions** for cloud inventory and configuration reads. 2. **Active permissions** for the selected test categories and supported rollback. Apply discovery permissions before running cloud discovery. Apply temporary active permissions only after the test categories are approved. ## Ready to Continue Continue when the cloud boundary, VM, identity, network access, permission owner, and cleanup owner are confirmed. {% content-ref url="/pages/74xr08DgNEibdsc9F6Z2" %} [Set Up the Cloud Agent](/enterprise/how-to-trigger-a-cloud-assessment/provider-runbooks) {% endcontent-ref %} # Set Up the Cloud Agent Prepare a cloud VM and attached identity, install the Pentest Copilot agent, and grant the required provider role. Complete [Cloud Assessment Prerequisites](/enterprise/how-to-trigger-a-cloud-assessment/configure-a-cloud-agent) before preparing the agent VM. ## 1. Prepare the VM and Identity You can use an existing VM and attached cloud identity or create them for the assessment. Existing infrastructure must be inside the approved cloud scope and meet the same identity, metadata, network, and operating system requirements. | Provider | Setup | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AWS | Use an EC2 instance in the approved account and region. Verify its instance profile contains the approved IAM role, attaching one if needed, and require IMDSv2. | | Azure | Use an Azure VM in the approved subscription and resource group. Verify its system-assigned or approved user-assigned managed identity, enabling or attaching one if needed. | | Google Cloud | Use a Compute Engine VM in the approved project. Verify its approved service account, attaching one if needed, and use the `cloud-platform` VM access scope when active testing is planned. | Confirm the VM can reach Pentest Copilot, cloud provider APIs, and the provider metadata service. The agent uses only the identity supplied through native VM metadata. Do not configure static cloud credentials or local CLI profiles for the agent. ## 2. Install the Agent 1. Open **Settings -> Agent** in Pentest Copilot. 2. Generate the launcher for the VM operating system. 3. Run the launcher on the cloud VM. 4. Confirm the new agent appears as connected in **Dashboard -> Agents** or **Settings -> Agent**. 5. Confirm the displayed host and network details match the VM. Keep the launcher and bootstrap token out of shell history, tickets, and shared documents. Do not assign an agent ID manually. {% hint style="info" %} The agent can connect and run capabilities that do not call provider APIs without a cloud read role. Cloud discovery will be incomplete or fail until read permissions are granted. {% endhint %} ## 3. Grant Cloud Permissions Use a standard provider role for the simplest setup: | Provider | Discovery | Full active scan in an isolated test environment | | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | AWS | [`ReadOnlyAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html) | [`AdministratorAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) | | Azure | [`Reader`](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/general#reader) at the VM resource group | [`Owner`](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/privileged#owner) inside the approved boundary | | Google Cloud | [`Viewer` (`roles/viewer`)](https://cloud.google.com/iam/docs/roles-overview#basic) at the project | [`Owner` (`roles/owner`)](https://cloud.google.com/iam/docs/roles-overview#basic) at the approved project | Administrator-equivalent roles are not required for installation or discovery. Use them only when broad active testing is authorized in an isolated environment, and remove them after cleanup. With narrower permissions, the assessment still runs but only authorized checks supported by the attached identity can complete. For custom roles, provider data-plane access, and the exact discovery actions, see [Cloud Permissions](/enterprise/cloud-assessment-reference/cloud-permissions-reference). ## 4. Verify the Setup Before discovery, confirm: * the agent is connected; * the attached identity matches the approved identity; * the discovery role is assigned; * AWS prefixes, Azure resource group, or Google Cloud project match the approved scope; * required provider APIs are enabled. Return to [Run a Cloud Assessment](/enterprise/how-to-trigger-a-cloud-assessment) and start cloud discovery. # Configure the Assessment Select cloud test categories, safeguards, and rollback behavior. Open **Modules -> Internal Assessment -> Run Assessment**. Choose **Assessment** for an existing cloud inventory or **Discovery + Assessment** to refresh inventory first. ## Target and Agent Select the discovered AWS account, Azure subscription/resource group, or GCP project and the connected agent on the approved cloud VM. The agent's attached workload identity performs provider operations. The selected categories and that identity's permissions must both match the approved scope. ## Test Categories Disable every category that is not authorized. | Category | Typical coverage | | ----------------------------------- | -------------------------------------------------------------------------- | | Cloud Identity Privilege Escalation | Roles, policies, identities, federation, and delegation | | Cloud Credential Access | Tokens, keys, signed URLs, secrets, and credential stores | | Cloud Data Exposure | Storage, databases, backups, messages, logs, and secrets | | Cloud Configuration Exposure | Public management, metadata, encryption, and trust boundaries | | Cloud Workload Execution | Commands, builds, functions, containers, startup actions, and code updates | | Cloud Authentication Bypass | IAM conditions, sessions, tokens, devices, and authentication policy | | Cloud Lateral Movement | Federation, hybrid identity, synchronization, and delegated access | | Cloud Policy Misconfiguration | Policies, bindings, encryption, event sources, and access settings | | Cloud Network Control | Firewalls, security groups, NSGs, DNS, peering, routes, and remote access | | Cloud Persistence | Keys, grants, scripts, devices, signed access, and management links | | Cloud Defense Evasion | Logging, diagnostics, flow logs, security services, sinks, and locks | | Cloud Destructive Impact | Deletion, disablement, quotas, keys, objects, recovery, and disruption | ## Optional Controls * **Validate pre-existing vulnerabilities** is for retesting stored findings. * **Regional monitoring coverage** should remain empty unless an approved unused-region test has prepared monitoring inventory. * **Rollback supported changes** restores only changes that implement automated rollback. It does not replace the engagement cleanup plan. * **RCE safeguards** should match the authorization and the desired behavior for already-compromised nodes. * Runtime limits stop remaining work after the configured duration. {% content-ref url="/pages/ArSzYQDa8xnxlD7aLJmK" %} [Advanced Settings](/enterprise/cloud-assessment-reference/advanced-cloud-assessment-settings) {% endcontent-ref %} ## Final Review Before starting, confirm: * provider scope and connected agent; * attached workload identity and temporary permissions; * enabled categories; * retest and regional-monitoring settings; * rollback and RCE safeguards; * runtime and schedule; * cleanup owner and stop conditions. Use **Start run** for immediate execution or **Schedule run** for the configured schedule. # Cloud Assessment Reference Optional reference material for cloud permissions, discovery coverage, advanced settings, cleanup, and support. Use [Run a Cloud Assessment](/enterprise/how-to-trigger-a-cloud-assessment) for the normal setup and assessment workflow. The pages below are reference material for specific environments or issues. | Reference | Use it when | | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | [Cloud Permissions](/enterprise/cloud-assessment-reference/cloud-permissions-reference) | Standard provider roles are not suitable or additional data-plane access is required. | | [Discovery Coverage](/enterprise/cloud-assessment-reference/cloud-discovery-coverage) | You need provider boundaries, supported inventory, partial-result behavior, or expected exclusions. | | [Advanced Settings](/enterprise/cloud-assessment-reference/advanced-cloud-assessment-settings) | The assessment uses retesting, regional monitoring coverage, or detailed rollback controls. | | [Safety and Cleanup](/enterprise/cloud-assessment-reference/cloud-assessment-safety-and-cleanup) | Active tests changed provider state or rollback requires verification. | | [Get Support](/enterprise/cloud-assessment-reference/troubleshoot-cloud-assessment) | The agent, discovery, assessment, or rollback does not complete as expected. | # Cloud Permissions Reference roles and least-privilege actions for cloud discovery and active assessment. The agent can connect without cloud permissions. Cloud permissions control discovery and active assessment coverage. ## Permission Levels | Goal | Access | | ------------------------------------------------------ | -------------------------------------------------------------------------- | | Connect the agent | No provider read or administrator role is required. | | Run discovery | Use a standard provider read role or the least-privilege actions below. | | Run selected active tests | Add the temporary actions required by the approved test categories. | | Run a full active scan in an isolated test environment | Use an approved administrator-equivalent role and remove it after cleanup. | Standard read roles are convenient baselines, not minimum permission sets. AWS `ReadOnlyAccess` and Google Cloud `roles/viewer` cover many services. Use custom roles when the customer requires tighter access. No single provider role covers every test. Data-plane, Microsoft Entra, organization-level, and service-specific permissions can require separate grants. ## AWS Discovery Actions The bounded AWS inventory uses: ``` sts:GetCallerIdentity ec2:DescribeVpcs ec2:DescribeVpcPeeringConnections ec2:DescribeSubnets ec2:DescribeFlowLogs ec2:DescribeSnapshots ec2:DescribeInstances ec2:DescribeSecurityGroups ec2:DescribeInstanceAttribute iam:GetInstanceProfile secretsmanager:ListSecrets sqs:ListQueues sqs:GetQueueAttributes ``` Several EC2 `Describe` actions require `Resource: "*"`. The collector still limits imported resources to the detected region and configured resource-name prefixes. Set `SECAGENT_AWS_RESOURCE_NAME_PREFIXES` to a non-empty JSON list of literal prefixes: ```json ["security-test-", "approved-lab-"] ``` Empty prefixes, spaces around a prefix, `*`, and `?` are rejected. ## Azure Discovery Access Azure discovery requires Resource Manager read access at the VM resource-group scope. The built-in `Reader` role is the standard baseline. A custom role can limit access to the approved resource providers. Depending on the environment, discovery can read metadata for: * identities, role assignments, and role definitions; * virtual machines, disks, networking, DNS, and snapshots; * Automation, Functions, Logic Apps, and Container Apps; * deployments, diagnostics, locks, Key Vault, and Storage. Key Vault and Storage have separate data planes. Add narrow data-plane list access only for resources approved for discovery. Microsoft Entra tests can require Microsoft Graph application permissions or directory roles. These are not included in Azure Resource Manager `Reader` or `Owner`. ## Google Cloud Discovery Access Grant list and get access for approved project services. Discovery can use: * Cloud Resource Manager and IAM; * Compute Engine, Cloud DNS, Cloud KMS, Logging, and Security Command Center Management; * Secret Manager, Cloud Storage, BigQuery, and Cloud SQL; * Cloud Build, GKE, Artifact Registry, Cloud Functions, Cloud Run, Eventarc, and Pub/Sub. Enable the APIs required for the approved inventory. Google Cloud evaluates both VM access scopes and service-account IAM roles. A restricted VM access scope can block an API even when IAM grants the action. ## Active Assessment Access After discovery: 1. Select the authorized test categories. 2. Grant the required provider actions or the approved broad role. 3. Confirm the identity can perform any required rollback actions. 4. Record temporary grants and their removal time. Remove temporary active permissions after the assessment and cleanup are complete. # Discovery Coverage Reference the scope, resource coverage, and collection limits of AWS, Azure, and Google Cloud discovery. Cloud discovery inventories the control plane visible to the identity attached to the agent VM. It creates a cloud scope for the detected provider environment, imports validated resources and relationships, and records collection gaps. Discovery does not read every resource in a provider account. The detected machine location and the enforced provider boundary decide what can be collected. ## Scope Boundaries | Provider | Discovered scope | Enforced boundary | | ------------ | --------------------------- | ----------------------------------------------------------------- | | AWS | Detected AWS account | EC2 instance region and configured literal resource-name prefixes | | Azure | Detected Azure subscription | Resource group containing the agent virtual machine | | Google Cloud | Detected project | Project attached to the Compute Engine VM | The agent rejects a configured provider, account, subscription, resource group, project, or metadata endpoint that does not match the machine metadata. Static credentials and local CLI profiles are not alternate credential sources. ## AWS Inventory AWS discovery runs only in the EC2 instance region. `SECAGENT_AWS_RESOURCE_NAME_PREFIXES` supplies one or more literal prefixes. Wildcards and empty prefixes are rejected. The default cloud collection can inventory prefix-bounded: * EC2 instances, instance metadata settings, security groups, network interfaces, EBS volumes, and instance-profile relationships; * VPCs, subnets, VPC peering, VPC flow logs, and EBS snapshots; * Secrets Manager secret metadata without secret values; * SQS queues and queue identifiers. The current automatic collection does not enumerate account-wide IAM, S3, KMS, GuardDuty, or CloudTrail resources because those paths cannot be constrained by the required literal name-prefix boundary. Lambda and EKS collection require exact in-scope resource names and are skipped when those exact allowlists are absent. {% hint style="info" %} A completed AWS discovery means the bounded collectors completed. It does not mean every account resource or region was inventoried. {% endhint %} ## Azure Inventory Azure discovery is restricted to the detected subscription and the agent VM's resource group. It can inventory: * the subscription, resource group, current managed identity, role assignments, and role definitions; * virtual machines, managed disks, VM extensions, bootstrap metadata, network interfaces, public IPs, virtual networks, peerings, load balancers, Bastion hosts, and snapshots; * DNS zones and records, network flow logs, diagnostic settings, and management locks; * Arc machines, Automation accounts, runbooks, and hybrid workers; * Functions, Logic Apps, API connections, Container Apps, and deployment history; * Key Vault key and secret metadata; * Storage accounts, queues, file shares, containers, and object metadata. Microsoft Entra tenant-wide collectors are not enabled by automatic cloud discovery. Defender pricing is also skipped because it is subscription-scoped rather than resource-group-scoped. Key Vault and Storage data-plane `401` and `403` responses are recorded as authorization boundaries. They prove that the attached identity could not cross that data-plane boundary. Other failed provider operations make the collection partial. ## Google Cloud Inventory Google Cloud discovery is restricted to the detected project. It can inventory: * the project, current service account, project IAM policy, custom role definitions, and supported dynamic-group evidence; * Compute Engine instances, disks, snapshots, images, networks, subnetworks, firewalls, load balancers, and forwarding resources; * Cloud DNS zones and records; * Cloud KMS key metadata, logging sinks, and Security Command Center service state; * Secret Manager secret metadata and Cloud Storage buckets, objects, versions, IAM policy, and legacy ACL metadata; * BigQuery datasets and tables; * Cloud SQL instances and databases; * Cloud Build builds and triggers; * GKE clusters and node pools; * Artifact Registry repositories and Docker image metadata; * Cloud Functions, Cloud Run services, Eventarc triggers, and Pub/Sub topics and subscriptions. The related Google Cloud APIs must be enabled. A disabled API, missing IAM permission, quota failure, or provider error makes discovery partial. ## What Discovery Does Not Read Cloud discovery avoids secret values during normal control-plane inventory. It records metadata and candidate locations that can feed explicitly enabled attack checks. Discovery does not: * accept static access keys, service-account key files, Azure CLI sessions, AWS profiles, or `gcloud` user credentials; * follow resources into another AWS account, Azure subscription or resource group, or Google Cloud project; * turn an authorization denial into successful coverage; * prove exploitability only because a resource exists; * treat missing graph data as proof that a resource is absent. ## Complete, Partial, and Not Cloud | Result | Meaning | Operator action | | ---------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Complete | All applicable bounded collectors completed, including explicit safe skips. | Confirm provider, scope, resource counts, and expected skips before attack configuration. | | Partial | At least one collector returned an error. Validated nodes and relationships are still imported. | Review the failed collector and operation, fix permissions, API state, quota, or connectivity, then rerun. | | Authorization boundary | Azure Key Vault or Storage rejected a data-plane metadata request with `401` or `403`. | Decide whether the boundary is intended. Grant narrow data-plane read access only when the resource is approved for collection. | | Not cloud | No supported cloud identity was detected on the VM. | Confirm the agent runs directly on EC2, Azure VM, or Compute Engine and can reach native instance metadata. Network discovery can still continue. | ## Coverage Verification After discovery: 1. Confirm cloud collection reached a final state in **Activity**. 2. Read the collection summary and note provider, root scope, node count, relationship count, errors, authorization boundaries, and explicit skips. 3. Confirm the cloud scope label and provider match the approved environment. 4. Compare important provider resources with **Dashboard -> Exploit Graph**. 5. Rerun after fixing partial collection. Do not compare finding counts across runs with different collection completeness. {% content-ref url="/pages/74xr08DgNEibdsc9F6Z2" %} [Set Up the Cloud Agent](/enterprise/how-to-trigger-a-cloud-assessment/provider-runbooks) {% endcontent-ref %} # Advanced Settings Configure retest mode, regional monitoring coverage, and rollback when an assessment requires them. Most assessments can leave these settings at their defaults. ## Validate Pre-existing Vulnerabilities Enable **Validate pre-existing vulnerabilities** only for a controlled retest of stored findings under the selected cloud scope. Retest mode runs supported validation steps from eligible stored findings and filters them by the selected test categories. It does not run the normal host and service assessment. Before enabling it, confirm the finding still belongs to the selected scope and the attached cloud identity remains approved. ## Regional Monitoring Coverage This setting supports the unused-region defense-evasion test. Leave it empty unless a current customer or provider monitoring inventory identifies an approved unmonitored region. Required fields are: | Field | Required value | | --------------------------- | ------------------------------------------------------------------ | | Authority type | `customer_monitoring_inventory` or `provider_monitoring_inventory` | | Coverage source ID | Stable identifier of the monitoring inventory | | Coverage source version | Exact version used for the assessment | | Observed at | ISO 8601 timestamp with timezone | | Valid until | Future ISO 8601 timestamp with timezone | | Selected unmonitored region | Region approved for the controlled test | | Unmonitored regions | Unique list containing the selected region | | Monitored regions | Unique list that does not contain the selected region | The provider and cloud scope ID must match the selected target. Expired, contradictory, or incomplete coverage information is rejected. Provider dependencies are also required: * **AWS:** AMI ID, subnet ID, security group ID, availability zone, and an owned termination-probe EC2 instance. * **Azure:** approved resource group and an immutable container image reference using `image@sha256:digest`. * **Google Cloud:** approved zone, public image URL, image numeric ID, and exact subnetwork URL. Do not infer monitoring coverage from missing resources or graph nodes. ## Rollback **Rollback supported changes after attack phase** is disabled by default. Some state-changing tests do not run unless it is enabled. When enabled, supported tests record restoration data and queue rollback after assessment work finishes. Rollback does not cover every provider action, exposed credential, external effect, or concurrent resource change. Confirm the attached identity can perform the required restoration actions, then verify provider state after the assessment even when rollback reports success. Use [Safety and Cleanup](/enterprise/cloud-assessment-reference/cloud-assessment-safety-and-cleanup) for post-assessment verification. # Safety and Cleanup Define stop conditions, understand rollback limits, and verify cloud cleanup after active testing. Cloud discovery reads supported inventory and configuration. Active assessment can read data, use credentials, execute workloads, or change provider state according to the selected categories and attached identity permissions. ## Before Active Testing Confirm: * written authorization covers the selected cloud scope and test window; * discovery completed or every accepted coverage limit is documented; * every enabled test category is approved; * temporary active permissions match those categories; * test data and assessment-owned resources are available where destructive proof is allowed; * provider audit logs and production alerts are monitored; * one operator can cancel the run; * one operator owns manual cleanup if rollback is unavailable or fails; * credential rotation and incident-response contacts are ready. Use [Configure the Assessment](/enterprise/how-to-trigger-a-cloud-assessment/configure-cloud-assessment) to review what each cloud category tests. ## Stop Conditions Stop new assessment work and begin verification when: * the agent reports a different provider scope or identity; * the run touches a resource outside written authorization; * a provider audit event cannot be matched to an expected test; * a production alert, outage, quota event, or workload failure occurs; * the agent disconnects during a state-changing operation; * rollback cannot read or restore its recorded baseline; * another operator changes the same resource during the test. Cancelling the assessment stops remaining scheduled work. It does not reverse provider operations that already completed. ## Rollback Limits Rollback is disabled by default. When enabled, supported tests record restoration data and queue cleanup after normal assessment work finishes. Rollback can remain incomplete when: * the provider does not support the required restoration; * the resource changed after its baseline was captured; * the attached identity lost permission before cleanup; * the resource was deleted or became unavailable; * a test failed before it recorded enough state; * the action requires credential rotation or external recovery. Rollback is not a provider-wide transaction. Verify provider state directly even when Pentest Copilot reports successful rollback. ## Cleanup Checklist After the assessment: 1. Confirm assessment and rollback work reached a final state. 2. Review provider audit logs for every identity and resource change. 3. Compare identity, policy, network, logging, key, workload, recovery, and storage configuration with the approved baseline. 4. Remove assessment-created resources, scripts, keys, grants, sessions, links, messages, and temporary data. 5. Remove temporary provider permissions. 6. Rotate credentials, tokens, signed URLs, certificates, and trust material exposed during testing. 7. Confirm modified or deleted recovery resources remain recoverable. 8. Record manual cleanup and independent verification. 9. Generate reports after findings and cleanup status are reviewed. Provider-specific review should include: * **AWS:** CloudTrail events, IAM changes, network controls, objects, keys, queues, scripts, and workload changes. * **Azure:** Activity Log and Entra audit events, RBAC and directory assignments, Key Vault and Storage access, network changes, extensions, applications, and workload settings. * **Google Cloud:** Cloud Audit Logs, IAM bindings, service-account keys, storage objects, images, builds, functions, services, triggers, firewall rules, logging sinks, and recovery artifacts. ## Cleanup Evidence Keep enough evidence to prove restoration without retaining exposed secrets: * assessment and check references; * provider audit event IDs and timestamps; * affected resource IDs; * baseline and restored configuration hashes or sanitized exports; * rollback status and manual cleanup owner; * credential rotation ticket or confirmation; * final verification time and reviewer. Do not store access tokens, private keys, secret values, signed URLs, session cookies, or full credential files in assessment notes. {% content-ref url="/pages/yIa5DS9u5uSEnjRhi5DZ" %} [Analysing Scan Results](/enterprise/analysing-scan-results) {% endcontent-ref %} # Get Support Complete customer-side checks and collect the information BugBase support needs for cloud assessment issues. Some cloud assessment issues require BugBase support. Do not repeatedly reinstall the agent, broaden permissions, or rerun active tests when the cause is unclear. ## Checks You Can Complete ### Discovery Is Partial Confirm that: * the standard discovery role or approved custom role is attached to the VM identity; * required provider APIs are enabled; * the AWS region and prefixes, Azure resource group, or Google Cloud project match the approved scope. After correcting an approved permission or API setting, rerun discovery. ### An Expected Resource Is Missing | Provider | Check | | ------------ | ------------------------------------------------------------------------------------------------------------- | | AWS | The resource is in the VM region, matches an approved name prefix, and belongs to a supported collector. | | Azure | The resource is in the agent VM's resource group and any required data-plane read role is assigned. | | Google Cloud | The resource is in the detected project, its API is enabled, and the service account has list and get access. | Use [Discovery Coverage](/enterprise/cloud-assessment-reference/cloud-discovery-coverage) for the complete provider inventory boundaries. ### Assessment Does Not Start Confirm that the selected target is the discovered cloud scope, the expected categories are enabled, and the attached identity has the required active permissions. ## Contact BugBase Support Contact support when: * the agent is not listed or remains disconnected; * discovery does not create a cloud scope after the required read role is assigned; * the detected provider or scope is incorrect; * an expected cloud check is not scheduled; * the assessment stops without a customer-actionable provider error; * rollback fails or provider state is unexpected. Do not rerun active tests until unexpected provider changes have been reviewed. ## Information to Include Provide: * deployment and tenant name; * assessment reference and timestamps; * cloud provider and scope ID; * selected agent ID and connection status; * discovery, assessment, or rollback status; * failed provider operation and sanitized audit event ID, when available. Do not include access tokens, secrets, private keys, signed URLs, session cookies, or credential files. # Analysing Scan Results Use results pages in this order: **Activity**, **Statistics**, **Attack Paths**, **Exploit Graph**, then **Reports**. ## 1. Confirm the Scan Finished Open **Activity -> Activity**. Check: * module status; * failed or cancelled submodules; * max runtime cancellations; * agent disconnects; * browser session failures; * target blocking or rate-limit events. * partial cloud collection errors. Do this before judging coverage. A partial run can still produce findings, but it should not be treated as complete coverage. {% content-ref url="/pages/QJ9ahgjtOWQNnN87Ivzs" %} [Activity](/enterprise/activity) {% endcontent-ref %} ## 2. Review Statistics Open: * **Modules -> External Assessment -> Statistics**, or * **Modules -> Internal Assessment -> Statistics**, or * **Modules -> Code Assessment -> Statistics**. Use Statistics to understand aggregate results: * total findings; * severity distribution; * vulnerability categories; * affected targets; * for internal and cloud assessments: hosts, services, cloud resources, identities, secrets, and compromise indicators. * for code assessments: repositories, vulnerable code paths, dependency risk, leaked secrets, and inventory coverage. {% content-ref url="/pages/TJuUXyT5cbg1xFPAH61r" %} [Statistics](/enterprise/modules/statistics) {% endcontent-ref %} ## 3. Triage Attack Paths Open: * **Modules -> External Assessment -> Attack Paths**, or * **Modules -> Internal Assessment -> Attack Paths**, or * **Modules -> Code Assessment -> Attack Paths**. Start with Critical and High findings. For each finding: 1. Open the finding detail page. 2. Read the summary, evidence, AI reasoning, remediation, and references. 3. Open the attack path drawer. 4. Confirm the graph chain makes sense. 5. Mark the finding Valid, False Positive, or Duplicate. 6. Retest when your team needs fresh verification. For code assessments, also review the repository, branch or commit, affected files, and whether a fix can be suggested or opened as a pull request. For cloud assessments, confirm the provider, discovered cloud scope, affected resource, effective identity, evidence, and cleanup status. {% content-ref url="/pages/Qq4eYhCnXnWRSOdpI5cq" %} [Attack Paths](/enterprise/modules/attack-paths) {% endcontent-ref %} ## 4. Inspect the Exploit Graph Open **Dashboard -> Exploit Graph**. Use the graph to answer: * What did discovery find under this root entity? * Which assets led to the finding? * Which browser session, trajectory, test case, or internal host was involved? * For code assessments, which repository, branch or commit, dependency, file, or inventory component was involved? * For cloud assessments, which identity, policy, resource, network, or trust relationship created the path? * Are there related findings on the same path? * Does the path cross a boundary your team considers out of scope? {% content-ref url="/pages/SVOgW3WWDsCNP6N3NZ7R" %} [Exploit Graph](/enterprise/exploit-graph) {% endcontent-ref %} ## 5. Generate Reports Open **Reports** after triage is complete. Before generating: * resolve obvious false positives; * mark duplicates; * confirm report root entity; * decide whether full output is needed; * choose severity filters for comprehensive reports. {% content-ref url="/pages/5R9A4WOfbwrPI78VKDKg" %} [Reports](/enterprise/reports) {% endcontent-ref %} ## What Not to Miss * Authenticated findings should identify the browser session or role used. * Code assessment findings should identify the repository, branch or commit, and affected file or dependency. * Code assessment inventory should be reviewed from **Modules -> Code Assessment -> SBOM** before sharing SPDX, CycloneDX, or AI-BOM exports. * Cloud findings should identify the provider scope, effective identity, affected resource, and rollback or cleanup status. * Internal findings may require cleanup or credential rotation even if they are later marked duplicate. * A clean scan is not proof of no risk if discovery, browser sessions, agents, or submodules failed. * Scheduled scans should be reviewed against approved scope and browser-session validity. # Attack Surface Attack Surface is the inventory view for root targets, discovered entities, connected agents, and MITRE ATT\&CK mapping. | Page | Use it for | | ------------------- | ----------------------------------------------------------------------------- | | **Attack Surface** | Review discovered exposure and inventory summaries. | | **All Entities** | Search graph entities across the workspace and inspect their properties. | | **Target Entities** | Manage external root targets and other dedicated upload targets when enabled. | | **Agents** | Confirm execution workers, reported subnets, interfaces, and capacity. | | **ATT\&CK Matrix** | Review actions and findings that have MITRE ATT\&CK mappings. | Before a run: * confirm external root targets match the authorization; * confirm the selected internal agent reports only the expected reachable subnets; * investigate unexpected discovered assets before expanding scope; * exclude or deny out-of-scope entities and paths; * confirm required agents are connected. Internal subnets come from agent inventory, cloud scopes come from cloud discovery, and code repositories come from the connected GitHub App. See [Target Assets](/enterprise/attack-surface/target-assets) for where each target type is managed. # Target Assets Target Assets manages external root targets. Assessment wizards select existing scope; they do not provide a general-purpose target-creation form. ## External Domains Add root domains only, such as `example.com`. Do not add a scheme, path, or query string. Subdomains and paths are discovered later. From **External Assessment -> Run Assessment -> Scope**, use **Manage target assets** when the required root domain is missing. After adding it: 1. confirm it is allowed by **Settings -> Domains**; 2. complete ownership verification when required; 3. return to Scope and select it. The target row shows verification and whitelist state. ## Other Assessment Scope * **Internal subnets** come from the reachable subnet inventory reported by the selected agent. * **Cloud scopes** are created by cloud discovery from the workload identity attached to the selected agent. * **Code repositories** come from the connected GitHub App installation. * **APK files** use their dedicated upload workflow when mobile analysis is enabled. Select discovered internal or cloud targets from **Internal Assessment -> Run Assessment -> Scope**. Select code repositories and their branch, PR, tag, or commit from **Code Assessment -> Run Assessment -> Scope**. ## Deleting or Changing External Targets Before deleting a target, check whether schedules, reports, attack paths, browser sessions, or graph data still depend on it. Update **Settings -> Domains** and **Settings -> Trajectories** when the approved external scope changes. # Agents The Agents page shows execution workers connected to the deployment. An agent is not an AI agent. It is a deployed runtime that receives jobs, executes tools, and reports results. ## Agent Roles | Role | Used for | Notes | | ----------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | **SANDBOX** | External browser work: crawling, browser-session recording, authenticated replay, web testing. | Needs browser dependencies and target network access. | | **CLOUD** | External/cloud-side tasks such as OSINT and non-browser jobs. | Usually managed by the deployment. | | **AGENT** | Internal network assessment and cloud assessment from a customer-controlled host. | Needs a route to approved subnets or an approved cloud machine identity. | ## What to Check Before a Scan * The required role is connected. * The agent status is healthy. * Public and private IPs match the expected environment. * Internal agents show the expected subnets and interfaces. * Job capacity is sufficient for the scan window. * The agent host has network access to in-scope targets. * Cloud-hosted agents run on the intended provider virtual machine with the approved attached identity. ## Common Agent Issues | Symptom | Check | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | External scan cannot start | Confirm a SANDBOX runner is connected or managed capacity is available. | | Browser session recording fails | Check SANDBOX status, browser access to target, WAF/bot blocking, and residential proxy setting. | | Internal discovery shows no subnets | Check AGENT network interface data and route to your network. | | Cloud discovery creates no CloudScope | Check that the AGENT runs on EC2, an Azure VM, or a Compute Engine VM with the approved machine identity. | | PCE Intercept/Inveigh cannot start | Confirm the selected AGENT exposes interfaces and at least one interface is selected. | | Internal jobs fail immediately | Check agent connectivity, endpoint protection allowlisting, outbound control-plane access, and local privileges. | {% content-ref url="/pages/qJVQdMWQN3SOOKDv02QD" %} [Download Agent](/enterprise/download-agent) {% endcontent-ref %} # Exploit Graph The Exploit Graph shows entities and relationships discovered during scans. Use it to understand how a finding was reached and what other assets are connected to it. ## What the Graph Contains * **Root entities** such as domains, subnets, IP addresses, and APK files. * **Discovered assets** such as web pages, APIs, hosts, services, users, groups, certificates, and cloud resources. * **Operational entities** such as browser sessions, goals, trajectories, test cases, and test case sets. * **Vulnerabilities** with severity, CVSS/CWE/CVE metadata, evidence, remediation, and validation state. * **Relations** showing discovery, execution, containment, use, compromise, or exploit-path links. ## Common Uses * Find all assets under a root domain or subnet. * Trace a vulnerability back to the page, API, session, host, or credential that produced it. * Inspect related nodes before marking a finding false positive or duplicate. * Confirm whether a path crossed an expected boundary. * Open a node’s properties for raw evidence and metadata. ## Actions * **Search** for entities by name, URL, IP, label, or identifier. * **Click a node** to view properties and connected relationships. * **Expand a node** to load neighbors. * **Open attack path drawers** from finding pages for a focused read-only path. * **Use retest mode** from finding pages when fresh validation is needed. {% content-ref url="/pages/Qq4eYhCnXnWRSOdpI5cq" %} [Attack Paths](/enterprise/modules/attack-paths) {% endcontent-ref %} # Entities Entities are the objects stored in the Exploit Graph. They represent scope, discovered assets, identities, testing context, and findings. The exact entity labels vary by assessment type and enabled capabilities. Operators normally need the groups below rather than the complete internal graph schema. ## Scope and Asset Entities | Entity | Meaning | | ------------------------------------ | ------------------------------------------------------------------------ | | **Domain** | External root domain or discovered subdomain. | | **IPAddress / Device / NetworkHost** | Discovered network address or externally visible host. | | **Subnet** | Internal network scope reported by an agent or created by discovery. | | **Host** | Internal computer, server, domain controller, or device. | | **Service** | Network service identified by port, protocol, product, or banner. | | **WebApplication / WebPage** | Web application and its discovered URLs. | | **CloudResource** | Provider resource, endpoint, identity, policy, or other cloud inventory. | | **Repository** | Source repository and associated code-assessment context. | | **APKFile** | Uploaded Android package when mobile assessment is enabled. | ## Identity and Access Entities | Entity | Meaning | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **User / Group** | Internal or directory identity and its memberships or privileges. | | **BrowserSession** | Recorded account context, browser state, and login actions for authenticated external testing. | | **Secret / Credential / Ticket** | Password, token, key, hash, Kerberos ticket, or other reusable authentication material. | | **CertificateAuthority / CertificateTemplate** | AD CS configuration relevant to certificate-based attack paths. | Treat identity and credential properties as sensitive. Access to the graph does not imply permission to copy them outside the workspace. ## Testing and Finding Entities | Entity | Meaning | | -------------------------- | ----------------------------------------------------------------------------- | | **Goal** | A testing objective produced for a target or user flow. | | **Trajectory** | An ordered browser, API, or mobile interaction flow. | | **TestCaseSet / TestCase** | Generated tests and their execution evidence. | | **Vulnerability** | A finding with target, severity, evidence, remediation, and validation state. | ## How to Use Entity Details Open an entity to inspect its properties and connected relations. During triage, confirm: * the entity belongs to the approved root scope; * timestamps and module references match the run being reviewed; * a browser session or identity matches the role described by the finding; * credential or compromise state is handled according to the cleanup plan; * the incoming and outgoing relations form a plausible path. Use [Relations](/enterprise/exploit-graph/relations) to understand how the graph connects these objects. Use [Attack Paths](/enterprise/modules/attack-paths) for normal finding triage; the raw graph is primarily for deeper investigation. # Relations Relations are directed edges between graph entities. They show how one entity was discovered from another, how entities are structurally connected, or how an attack path moved through the environment. ## How to Read a Relation A relation records one of these facts: * How was this entity discovered? * What does this entity belong to? * Which asset runs this service? * Which browser session, role, or identity was used? * Which test case set produced this vulnerability? * Which internal object can control or compromise another object? Example: ``` Domain -> BrowserSession -> WebPage -> Goal -> Trajectory -> TestCaseSet -> Vulnerability ``` This chain means the vulnerability was found by testing a trajectory generated from a page under the domain, inside a specific browser session. Each **BrowserSession** represents one recorded role or identity, such as an unauthenticated visitor, a standard user, or an admin. Pages, goals, trajectories, and test case sets are grouped under that session so the graph can distinguish what was reachable or testable from each identity. **TestCaseSet** is the main testing node in this path. It contains the generated test cases for a category or trajectory. Individual **TestCase** details may appear in deeper finding or debugging views, but the high-level relation should be read through the TestCaseSet rather than as a separate normal hop for every graph path. ## Relation Metadata Some relations include module or submodule references. These are useful for support and debugging because they connect graph output back to Activity, logs, and LLM traces. ## Triage Tips * A vulnerability without a plausible incoming path should be reviewed carefully. * A duplicate finding should link back to the original finding or share the same affected path. * Internal relations involving credentials, tickets, AD objects, or delegation should be reviewed before cleanup decisions. # Modules Modules contain assessment launch and result-review workflows. ## External Assessment | Page | Use it for | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | **Run Assessment** | Choose Discovery, Assessment, or Discovery + Assessment; configure scope, authentication, traffic, attack vectors, and automation. | | **Statistics** | Review aggregate external results. | | **Attack Paths** | Triage external findings and retest them. | ## Internal Assessment | Page | Use it for | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Run Assessment** | Choose Discovery, Assessment, or Discovery + Assessment; select the agent, subnet or cloud scope, exploit families, safeguards, and automation. | | **Statistics** | Review aggregate internal and cloud results. | | **Attack Paths** | Triage internal and cloud findings and retest them. | Cloud assessment uses Internal Assessment. Discovery detects provider scope from the workload identity attached to the selected cloud-hosted agent. {% content-ref url="/pages/cycdJfiZOF1JvOhhmyH7" %} [Run a Cloud Assessment](/enterprise/how-to-trigger-a-cloud-assessment) {% endcontent-ref %} ## Code Assessment | Page | Use it for | | ------------------ | ------------------------------------------------------------------------------------------------------------ | | **Run Assessment** | Select repositories and branch, PR, tag, or commit targets; configure checks, automation, and the final run. | | **Statistics** | Review severity, category, repository, and trend summaries. | | **Attack Paths** | Triage confirmed source, dependency, secret, authorization, and business-logic findings. | | **SBOM** | Review inventory verification and download SPDX, CycloneDX, and AI-BOM exports. | ## Before Starting Confirm: * target scope and activity are authorized; * required agents or the GitHub App are connected; * authentication and branch/commit selections are intentional; * rate limits, exploit families, and runtime warnings are acceptable; * the final Review matches the intended run or schedule. Monitor execution under **Activity** and manage existing schedules under **Activity -> Schedule**. # Statistics The **Statistics** page provides a high-level overview of vulnerabilities and findings for a given assessment scope. It can be viewed **per assessment** or **per root entity** (Domain, Subnet, Repository, or APK file) to help prioritize remediation efforts. * **Views** – Separate dashboards are available for **External Assessments**, **Internal Assessments**, and **Code Assessments**, each tailored to the nature of the test. * **Metrics shown:** * Total vulnerabilities and severity breakdown * Percentages of vulnerabilities by severity. External assessments follow the active severity display mode: CVSS uses Critical, High, Medium, Low, or Informational, while VRT uses Bugcrowd-style P1-P5 priorities when VRT data is available. * Most common CWE IDs and vulnerability types * Top vulnerabilities by CVSS score * Vulnerabilities grouped by affected asset or relation * Time-based trends of vulnerability discovery * For internal assessments: discovered subnets, hosts, services, ports/protocols, and secrets found * For code assessments: repository findings, code issue categories, dependency risk, leaked secrets, and inventory coverage Set the external severity mode from **Settings -> External -> Severity Display**. Choose **CVSS** for standards-aligned risk and compliance views. Choose **VRT** for bug bounty style prioritization using Bugcrowd's web and API taxonomy. See [Bugcrowd VRT](https://bugcrowd.com/vulnerability-rating-taxonomy). This page acts as the **central reporting view** for assessment results, helping security teams understand exposure, identify recurring weaknesses, and track progress over time. # Attack Paths The Attack Paths page is the triage surface for every vulnerability discovered in a module. Each row is a single finding with its full attack chain attached, from the entry point to the exploited node It is available under: * `Modules → External Assessment → Attack Paths` * `Modules → Internal Assessment → Attack Paths` * `Modules → Code Assessment → Attack Paths` ### Findings list The list groups findings into three triage tabs. Each tab shows a live count for the currently applied filters. | Tab | Meaning | | ------------------- | -------------------------------------------------------------------------------------------- | | **Valid** | Confirmed findings that need attention. Default tab. | | **False Positives** | Findings the Validator (or a reviewer) marked as not exploitable. | | **Duplicates** | Findings that re-state an already-reported issue. Each duplicate links back to its original. | A `N findings total` indicator on the right shows the combined count across all three tabs for the current filter set. #### Filters The filter bar above the tabs scopes every tab simultaneously. * **Search**: free-text match against vulnerability name (debounced). * **Domain** *(external)* / **Subnet** *(internal)* / **Repository** *(code assessment)*: multi-select. You must pick at least one target before findings load. * **Type**: vulnerability category (XSS, SSRF, Auth Bypass, etc.). * **Severity**: filters by the active severity display mode. CVSS mode uses Critical, High, Medium, Low, or Informational. VRT mode uses Bugcrowd-style P1-P5 priorities for external assessment findings. * **Sort**: `Critical first` or `Informational first`. Selected domains and subnets persist across navigations within the session. External assessment severity display is controlled from **Settings -> External -> Severity Display**. Choose **CVSS** when you need standards-aligned severity data for compliance and remediation tracking. Choose **VRT** when your team wants bug bounty style triage against Bugcrowd's web/app Vulnerability Rating Taxonomy. See [Bugcrowd VRT](https://bugcrowd.com/vulnerability-rating-taxonomy). #### Row layout Each row shows: severity pill, vulnerability name, type, target host/path, and discovery date. Clicking a row opens the **Finding detail** page for that vulnerability. *** ### Finding detail page Selecting a finding opens a dedicated report page at: ``` /app/modules/{external-assessment|internal-assessment|code-assessment}/attack-paths/{vuln_id} ``` This page is a full vulnerability report, designed to be read top-to-bottom, exported, or shared. The right-hand sidebar holds properties, actions, and a jump-to navigator. #### Header * Breadcrumb back to the findings list * Vulnerability name (with target host appended) * Severity pill, CWE, published date, and a `Verified` badge if the Validator confirmed the finding. External findings follow the active CVSS/VRT display mode. #### Duplicate banner If the finding is a duplicate, a banner at the top names the original it duplicates (clickable) and shows the LLM-generated reason for the duplicate match. #### Sections 1. **Summary**: Markdown-rendered vulnerability description. 2. **Details**: severity data, CVSS score, CVE ID, CWE, type, target, and discovery date. External findings can show CVSS severity and VRT priority when VRT data is available. 3. **AI Reasoning**: a staged timeline of how the Copilot arrived at this finding: 4. **Remediation**: suggested fix, rendered from Markdown. 5. **References**: auto-linked CVE (NVD), CWE (MITRE), and any external reference URLs. 6. **Attack Path**: opens the full graph drawer (see below). #### Sidebar * **Properties**: severity, CVSS, CVE, CWE, type, target, date, verified status. * **Status pill**: change the finding between `Valid`, `False Positive`, and `Duplicate`. Requires the `vulnerabilities.update_status` permission. * **View Attack Path**: opens the graph drawer in read-only mode. * **Retest**: opens the graph drawer in retest mode. Requires the `scans.retest` permission. * **Jump to**: quick links to every section of the report. When indicator hits exist, a highlighted shortcut group lists each hit modification individually. The sidebar can be collapsed with the chevron in its top bar. *** ### Attack path drawer The drawer renders the full chain of nodes for the finding #### View mode Read-only graph for inspecting the chain. Useful for understanding *how* the Copilot reached the vulnerability. #### Retest mode Toggle **Retest mode** in the drawer to: 1. Pick a **start node** anywhere in the chain. The retest will replay every step from that node onward. 2. *(Internal assessments)* select the agent that should run the retest. 3. *(External assessments)* optionally pin a browser session. 4. *(Code assessments)* confirm the repository and branch or commit context before retesting. 5. Click **Start retest** to enqueue. Retest results flow back into the same finding and update its verification status. The button is disabled if your role lacks `scans.retest`. *** ### Status workflow | Status | When to use it | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Valid** | Default for new Copilot-confirmed findings. | | **False Positive** | Mark when manual review shows the vulnerability isn't exploitable. Moves the finding to the False Positives tab. | | **Duplicate** | Use when the finding repeats one already reported. Pair with the duplicate metadata so the report links back to the original. | Status changes are written immediately and reflected on the list (counts and tab membership update) without a page reload. # Activity Activity is the operational view for scans and scheduled work. Use it while a scan is running and when investigating what happened after a scan finishes. ## Activity Page Open **Activity -> Activity**. Use this page to check: * execution type, such as External Attack Phase, Internal Attack Phase, External Discovery Phase, Internal Discovery Phase, Calibration Phase, Retesting, or Pre-Flight Test; * module status; * start and end time; * root target; * progress through submodules; * failure or cancellation state. Click a module row to open the activity detail page for that module. Historical and backend execution records can retain phase-based names even though new external and internal work is configured from the unified **Run Assessment** page. ## Activity Detail The detail page is the first place to inspect a scan that is slow, failed, cancelled, or producing unexpected results. Check: * which submodules ran; * which submodules are pending, running, completed, failed, or cancelled; * when each stage started and ended; * whether failures are isolated or repeated; * whether a max runtime limit cancelled remaining work. ## Attack Logs Open **Activity -> Attack Logs** for lower-level event logs. Use logs when the module-level view is not enough, for example: * agent disconnected; * browser session failed; * target blocked scanner traffic; * rate-limit calibration failed; * submodule timed out; * RabbitMQ or worker pickup was delayed; * internal agent could not reach a host or subnet. {% content-ref url="/pages/a9GP0W0haHX5Y0rHbGoi" %} [Logging](/enterprise/activity/logging) {% endcontent-ref %} ## Schedules Open **Activity -> Schedule** to view and delete one-time or recurring schedules. {% content-ref url="/pages/LLoc9R3DJqOcKInTTM8W" %} [Scheduling](/enterprise/activity/scheduling) {% endcontent-ref %} # Logging Logs record scan and system events that are useful for troubleshooting. They are separate from final findings: a scan can produce useful logs even when it produces no vulnerabilities. ## When to Use Attack Logs Use **Activity -> Attack Logs** when: * a module or submodule failed; * a scan is stuck or slower than expected; * a browser session stopped working; * a target blocked or rate-limited requests; * an internal agent disconnected; * an internal host or service was unreachable; * a scheduled run did not start; * you need scan evidence for review or escalation. ## What to Look For | Symptom | Log evidence to check | | ---------------------- | --------------------------------------------------------------------------------------------- | | Browser session failed | validation errors, replay failures, expired auth, missing storage, verification URL mismatch. | | Target blocked scanner | HTTP 403/429 patterns, WAF pages, captcha loops, rate-limit calibration failures. | | Internal agent issue | disconnects, heartbeat gaps, job pickup failures, route or interface errors. | | Module timeout | max runtime cancellation, submodule timeout, long-running job status. | | Queue delay | scheduled/running state with delayed worker pickup. | ## Filtering Filter logs by time range, module, severity, and text search. Start with the module reference from **Activity -> Activity**, then narrow to the failing time window. # Scheduling Schedules start configured runs later or on a recurring cadence. Create them from the same Run Assessment wizard used for immediate work so the schedule captures the selected targets, settings, agent assignment, and safety controls. ## Create a Schedule From the applicable **Run Assessment** page: 1. Choose the intent when the assessment type supports it. 2. Select targets, repositories, or subnets. 3. Configure authentication, rates, exploit controls, exclusions, agents, and other run-specific options. 4. In **Automation**, enable scheduling. 5. Choose: * **Doesn't repeat** and a future run time; or * **Repeats** with an interval and unit. 6. Confirm the complete configuration in **Review**. 7. Select **Schedule run**. The schedule modal supports interval units of minutes, hours, and days. {% hint style="info" %} Schedules are created from a configured run, not from an empty scheduler form. {% endhint %} ## Manage Schedules Open **Activity -> Schedule**. Use this page to: * switch between one-time and recurring schedules; * filter by schedule status; * open schedule details, including the saved payload and scan configuration reference; * delete schedules. The Activity schedule page is for reviewing and managing schedules. Start new schedules from the relevant module's run flow. ## Important Behavior Schedules use the payload and saved scan configuration created when the schedule is submitted. If you later change browser sessions, rate limits, allowed exploits, trajectory scope, target scope, responder/PCE Intercept settings, exclusions, or agent assignment, review whether the schedule must be recreated. Recurring schedules reuse the stored run payload each time they fire. Confirm that the selected agents, credentials, browser sessions, and target scope will still be valid for each future run window. ## Before Scheduling Production Scans Confirm: * the scan window is approved; * the required agents are expected to be online; * browser sessions will still be valid; * rate limits match the target's production capacity; * internal exploit families are approved for the scheduled window; * reports and on-call contacts are planned for high-impact runs. # Reports Use **Reports** to generate and download PDF reports from graph data and findings. ## Report Types The Reports page exposes two report types: | Report type | UI value | Use for | | ------------------------ | ----------- | ---------------------------------------------------------------------- | | **Comprehensive Report** | `general` | Technical assessment detail for security teams and remediation owners. | | **Executive Report** | `executive` | Summary-level reporting for leadership and risk owners. | ## Supported Root Entities Reports can be generated for these root entity types: * **Domain** * **IP Address** * **Subnet** The entity picker searches existing graph entities of the selected type. ## Generate a Report 1. Open **Reports**. 2. Click **Generate Report**. 3. Select **Comprehensive Report** or **Executive Report**. 4. Select the root entity type. 5. Search for and select the root entity. 6. Choose report options. 7. Click **Generate Report**. Generation runs asynchronously. The report table shows an in-progress row with progress and current step. When generation completes, the row is replaced by the completed report. ## Report Options ### Full Output By default, request/response and job output are truncated for readability. Enable **Full Output** when your team needs complete raw evidence. Full-output reports can be large and slower to generate, open, and share. ### Severity Filter For **Comprehensive Report**, choose which severities appear in finding detail: * Critical * High * Medium * Low * Info Selecting all severities or none sends no severity filter and includes all severities. ### Debug Report Version The **Debug Report Version** field appears only for users with debug access. Leave it blank unless you need to regenerate a specific report version. ## Report Table The table shows: * report name or entity name; * report type; * entity type; * output options, such as truncated or full output; * generation time; * download action. Use search to find reports by report ID, filename, root entity ID, entity name, report type, or entity type. ## Before Sharing Check: * finding statuses are correct; * duplicates and false positives have been triaged; * the selected root entity matches the approved scope; * full output does not expose secrets or unnecessary internal data; * internal findings that changed state have cleanup notes available. # Vulnerability Testing Coverage Vulnerability families available to assessment runs. The definitive coverage for a run is the category list shown in **Run Assessment -> Scan settings**. Availability can vary by deployment, target type, permissions, and installed assessment capabilities. Selecting a category permits applicable tests; it does not guarantee that every technique runs against every target. Discovery data, reachable functionality, authentication, safeguards, and runtime limits determine which tests are relevant. ## External Assessment External categories are grouped in the UI: | Group | Categories | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Access control & identity** | Authentication, Authorization, IDOR, OAuth, SAML, JWT | | **Injection** | SQL Injection, NoSQL Injection, Command Injection, SSTI, XML, Email Injection | | **Client-side** | XSS, CSRF, Open Redirect, Prototype Pollution | | **Server-side & request** | SSRF, Request Smuggling, Mass Assignment, Serialization, Cache, Directory Traversal, File Upload, WebSockets | | **Information & application logic** | Information Disclosure, Prompt Injection, Prompt Leakage, Business Logic | All available categories are selected by default for broad coverage. Disable categories that are outside the engagement authorization. Authenticated coverage can test the same categories from each selected browser-session role. A category being selected does not replace the need to record the relevant user flow or provide a valid session. ## Internal Assessment Internal categories depend on the exploit and check families enabled for the tenant. Common families cover: * credentials, secrets, and anonymous access; * configuration and policy weaknesses; * privilege escalation and ACL abuse; * Active Directory trusts, delegation, and Kerberos tickets; * AD CS certificate authorities and templates; * lateral movement and remote code execution; * authentication bypass and information disclosure; * cloud identity, credential, data, policy, workload, network, persistence, defense-evasion, and destructive-impact paths. Some families can modify directory, host, credential, ticket, or cloud state. Review [Internal Assessment Destructive Actions](/enterprise/how-to-trigger-an-internal-scan/internal-assessment-destructive-actions) before enabling them. ## Code Assessment Code Assessment checks are outcome-based rather than mapped one-to-one to external attack vectors: * vulnerable source-code paths; * open-source dependency risk; * leaked secrets and credentials; * business logic and authorization; * AI inventory for AI-BOM output. The selected repository target—branch, PR, tag, or commit—defines which code is reviewed. ## Interpreting a Clean Result No findings does not prove that every category was exercised. Before judging coverage, confirm: * Discovery completed sufficiently for the target; * selected browser sessions and agents remained healthy; * relevant pages, APIs, hosts, services, or repositories were reachable; * the run was not truncated by a runtime, rate, or concurrency limit; * Activity does not show failed or cancelled submodules; * exclusions and trajectory rules did not remove the intended surface. # Settings Configure tenant, scan, access, agent, integration, and scope settings. Settings contains the controls that affect scan eligibility, scan behavior, access, integrations, and scope. Review these pages before your first scan. ## Usage Open **Settings -> Usage** to check scan entitlement and current consumption. Use this page to verify: * available credits or scan-hour allowance; * running and queued scan counts; * plan or billing state; * feature availability, such as internal assessment, scheduled scans, API/MCP access, reports, and attack paths; * whether scan launch is blocked by missing domain setup, usage limits, feature access, or agent availability. Credits are counted as worker runtime. Parallel workers may finish faster, but credit usage reflects the combined runtime of the workers. ## External Open **Settings -> External** to set tenant-wide defaults for external scans. The page title is **External Assessment**. Tenant-wide external controls include: * severity display mode for external assessment findings; * default attack vectors; * custom headers; * max module runtime, in seconds. Shared-trial workspaces may not permit tenant-wide External settings changes. Use the per-run controls in **External Assessment -> Run Assessment**; opening Settings should not be required to configure an ordinary run. Severity display mode controls whether external assessment dashboards, finding lists, filters, and charts show the CVSS severity band or the Bugcrowd Vulnerability Rating Taxonomy priority. * **CVSS** shows standards-aligned severity data derived from CVSS scoring. Choose it for compliance reporting, general remediation tracking, and teams that already triage by Critical/High/Medium/Low. * **VRT** shows Bugcrowd-style P1-P5 priority data for web and API findings. Choose it when you want bug bounty style prioritization that maps findings to a shared web/app vulnerability taxonomy. Learn more about Bugcrowd VRT: Rate limits, browser sessions, starting URLs, trajectory scope, and browser behavior are configured in **External Assessment -> Run Assessment**. Per-run settings can override tenant defaults for the submitted run. {% content-ref url="/pages/JqTFyGv6qHEq1MBlbEzs" %} [Configure Scan Settings for External Assessment](/enterprise/how-to-trigger-an-external-scan/configure-scan-settings-for-external-assessment) {% endcontent-ref %} ## Internal Assessment Settings Internal assessment settings are configured in the launch flow, not from a separate Settings sidebar page. Per-subnet controls such as allowed exploits, entity exclusions, agent assignment, PCE Intercept/Inveigh, RCE safeguards, and runtime warnings are configured in **Modules -> Internal Assessment -> Run Assessment**. ## Domains Open **Settings -> Domains** to manage external scope. * **Whitelist** defines domains approved for external work. * **Blacklist** blocks domains even if they are discovered through an approved root. Blacklist takes precedence over whitelist. {% content-ref url="/pages/0ajjGH6BFpdgg11q6axz" %} [Domains](/enterprise/settings/domains) {% endcontent-ref %} ## Domain Verification Open **Settings -> Domain Verification** to prove DNS ownership of root domains before gated external workflows. {% content-ref url="/pages/KbaSIgSbMUURkiHIWkMl" %} [Domain Verification](/enterprise/settings/domain-verification) {% endcontent-ref %} ## Trajectories Open **Settings -> Trajectories** to create host/path rules for discovered API and browser flows. Use these rules when your team wants to include or exclude specific endpoint paths across runs. {% content-ref url="/pages/M0MfkR8EXMrAeSyOno1b" %} [Trajectories](/enterprise/settings/trajectories) {% endcontent-ref %} ## Agent Open **Settings -> Agent** to download agent installers, view connection details, and manage agent runtime settings. Use it to confirm: * agent role, such as SANDBOX, CLOUD, or AGENT; * connection status; * public and private IPs; * subnets and network interfaces; * job-capacity settings when the agent exposes them. {% content-ref url="/pages/qJVQdMWQN3SOOKDv02QD" %} [Download Agent](/enterprise/download-agent) {% endcontent-ref %} ## API Keys Open **Settings -> API Keys + MCP** to create, rotate, or revoke API keys for REST and MCP clients. API keys inherit the permissions and workspace/organization scope of the creating user. They cannot bypass scan launch policy. {% content-ref url="/pages/630pgqCxCXa6IGmOxWjz" %} [API Keys & MCP Server](/enterprise/settings/api-keys-and-mcp-server) {% endcontent-ref %} ## Integrations Open **Settings -> Integrations** to connect supported external systems. Availability depends on the deployment and feature flags. Integration surfaces are tenant-gated. Connectors shown as **Coming soon** are visible in the UI but not active for the tenant. ## Email Identities Open **Settings -> Email Identities** when browser-session recording needs controlled email addresses for OTPs, magic links, or account creation flows. Each identity can store **Account & access notes** for its target accounts, credentials, roles, and connected services. The selected identity's notes are shown in Browser Session Manager. Plan email/phone routing during onboarding if target applications only allow approved domains or phone numbers. {% content-ref url="/pages/7O8ZO3wIolyqrWDTE0BK" %} [Email Identities](/enterprise/settings/email-identities) {% endcontent-ref %} ## Users and Account Use **Settings -> Users** and **Settings -> Account** to manage team access and account details. Confirm role assignments before giving users scan, report, API-key, or settings permissions. ## Debug and Preflight Some deployments expose **Settings -> Debug** and **Settings -> Preflight Test**. Manual Crawler and other interactive diagnostic capabilities are available only when Debug Mode is enabled. Use preflight checks before high-stakes scans to validate queue health, job concurrency, connectivity, and crawler behavior. # API Keys & MCP Server Pentest Copilot API keys let external tools call the REST API and the platform MCP server ### Create an API Key You need permission to manage API keys in your workspace or organization. 1. Open **Settings -> API Keys + MCP** in Pentest Copilot. 2. Select **Create API key**. 3. Enter a name that identifies the integration, such as `Claude Desktop`, `Cursor`, or `CI pipeline`. 4. Copy the raw key when it is shown. The raw key is only shown once when you create or rotate it. If the key is lost or exposed, rotate it from the same page. API keys are scoped to your workspace or organization. A key inherits the permissions of the user that created it, so MCP tools and REST endpoints enforce the same access controls as the web app. ### REST API Usage Send API keys to REST endpoints with the `X-API-Key` header. ```bash curl \ -H "X-API-Key: " \ https:///api/auth/me ``` The OpenAPI schema is available at: ``` https:///api/docs ``` ### MCP Server Usage Use the MCP endpoint for external MCP clients: ``` https:///mcp ``` Most MCP clients should send the key as a bearer token: ```json { "mcpServers": { "pentest-copilot": { "url": "https:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` The MCP server also accepts `X-API-Key: `, but the bearer-token form is the recommended MCP client configuration. ### Available MCP Workflows The exact tools shown to a client depend on the API key's permissions and enabled product features. Common MCP workflows include: * Asset management: `list_assets`, `get_asset`, `create_root_target`, `delete_root_target` * Graph exploration: `search_graph`, `get_graph_node`, `get_graph_root_nodes` * Scan orchestration: `start_external_discovery`, `start_external_assessment`, `start_internal_discovery`, `start_internal_assessment` * Scan job control: `get_jobs`, `cancel_submodule`, `rerun_submodule` * Settings and reporting: `get_settings`, `update_settings`, `generate_report`, `list_reports` * Logs and stats: `get_attack_logs`, `get_module_stats` ### Scan Launch Requirements API keys and MCP clients cannot bypass scan launch policy. Starting discovery or assessment through MCP is subject to the same checks as starting a scan in the web app: * The workspace or organization must have scan usage available. * Plan, payment, and credit restrictions still apply. * The API key must be scoped to an active workspace or organization. * External scans require the requested domain to be in the workspace or organization scope. * Internal scans require the internal assessment feature and a connected agent. * The requested target must belong to the API key's workspace or organization. If any of these checks fail, the MCP tool returns an error instead of starting the scan. ### Rotate or Revoke Keys Rotate a key when it is exposed, when a user leaves, or when an integration owner changes. Revoke keys that are no longer used. Revocation takes effect immediately for both REST API calls and MCP calls. ### Troubleshooting `401 Missing API key` : The MCP or REST request did not include an API key. `401 Invalid API key` : The key is incorrect, revoked, or belongs to a workspace that no longer matches the request. `403 API key is not bound to a workspace; please re-create it.` : The key is missing workspace scope. Create a new key from **Settings -> API Keys + MCP**. `403` role or feature errors : The key's permissions or plan do not allow the requested tool. Payment, credit, usage, or scope errors : The scan was blocked by the same launch requirements enforced in the web app. Confirm the domain is in scope and the workspace has scan usage available. Agent availability errors : Internal scans require a connected agent. External scans may be temporarily unavailable if required scanning capacity is unavailable. ### Security Best Practices * Use one API key per MCP client or integration. * Store keys in a secrets manager or the MCP client's secure configuration. * Do not commit keys to source control, tickets, chat, or documentation. * Rotate keys regularly and immediately after exposure. * Revoke old keys instead of reusing them across tools. * Treat MCP clients as privileged automation. Depending on the key's role, a client can start scans, modify targets, cancel submodules, generate reports, and read attack data. # Email Identities Manage monitored test inboxes and their account and access notes. Email identities are workspace-scoped inboxes that Pentest Copilot can use for sign-up, email OTP, invitation, and magic-link flows. Each identity has a label, a unique email address, and optional notes describing the accounts and access associated with it. ## Add account and access notes 1. Open **Settings -> Email Identities**. 2. Find the identity you want to document. 3. Enter the details under **Account & access notes**, directly below the identity's email address. 4. Click **Save notes**, or press **Ctrl/Cmd + Enter**. Notes can also be entered while creating an identity. Clear the text and save to remove existing notes. Use a simple service-by-service format so your team can understand the account: ``` Google Email: test-admin@example.com Password: Role: Workspace administrator GitHub Username: test-admin Password: Organization access: Example Security ``` Notes accept up to 10,000 characters. {% hint style="warning" %} Notes may contain credentials. Store only assessment-specific test access, keep workspace membership restricted, and remove credentials when they are no longer valid. {% endhint %} ## Use notes in browser sessions When you select an identity in **Browser Session Manager**, its **Account & access notes** appear immediately below the **Email Identity** selector. If the identity has no notes, the manager shows an empty-state message that points you back to the settings location. Reopen Browser Session Manager if it was already open when the notes changed. # Domains Use **Settings -> Domains** to manage external domain scope. ## Whitelist The whitelist is the allow-list for external discovery and assessment. Add domains that are approved for testing. Examples: ``` example.com *.example.com *.dev.example.com ``` Use the whitelist to keep discovered related domains inside approved scope. Domain scope controls which domains are allowed. Domain ownership verification is handled separately in **Settings -> Domain Verification**. {% content-ref url="/pages/KbaSIgSbMUURkiHIWkMl" %} [Domain Verification](/enterprise/settings/domain-verification) {% endcontent-ref %} ## Blacklist The blacklist blocks domains even if they would otherwise be included by discovery or whitelist rules. Examples: ``` analytics.example.com *.third-party.example payments-vendor.com ``` Use the blacklist for: * third-party services; * production areas excluded from the engagement; * domains owned by partners or vendors; * targets that must not receive automated traffic. ## Rule Precedence Blacklist takes precedence over whitelist. If `*.example.com` is whitelisted and `billing.example.com` is blacklisted, `billing.example.com` is excluded. ## Before a Scan Confirm: * every intended root domain is listed; * excluded third-party domains are blacklisted; * wildcard rules do not accidentally include unrelated assets; * scheduled scans still match the current domain policy. # Domain Verification Verify root-domain ownership before external recording and scanning. Use **Settings -> Domain Verification** to prove ownership of root domains before external Run Assessment, browser-session recording, or Manual Crawler when verification is required. The External Run Assessment **Scope** step shows verification state and links to the relevant scope-management flow. ## Verification Flow 1. Open **Settings -> Domain Verification**. 2. Select the root domain that needs verification. 3. Publish the DNS TXT record shown in the challenge. 4. Click **Verify Now**. 5. Wait for the status to change to **Verified**. If the DNS challenge expires or needs to be regenerated, use **Refresh Challenge** and publish the new TXT value before trying again. ## Statuses | Status | Meaning | | -------------- | -------------------------------------------------------------------------------------- | | **Verified** | The domain passed ownership verification and can be used for gated external workflows. | | **Pending** | A challenge exists, but the TXT record has not been confirmed yet. | | **Unverified** | No valid ownership proof has been completed for the root domain. | ## When Verification Blocks Work Verification may be required before: * recording browser sessions; * using Manual Crawler; * starting an external Discovery, Assessment, or Discovery + Assessment intent. If a flow is blocked, open **Settings -> Domain Verification**, verify the root domain, then return to the scan or browser-session flow. Enterprise managers can disable verification enforcement for some deployments. Shared trial environments usually require DNS TXT verification unless Bugbase support grants an exception. Manual Crawler is additionally available only in Debug Mode. # Trajectories Add Trajectory Whitelist and Blacklist The Trajectory Whitelist and Blacklist feature gives you precise control over which API endpoints are included or excluded during external security assessments. This allows you to define the exact scope of automated testing, ensuring that scans focus only on relevant API endpoints. ### Key Features * **Per-host rules** — Rules are applied independently for each host or domain. * **Regex pattern matching** — Use regular expressions to match path patterns. * **Blacklist takes precedence** — Any path matching a blacklist rule is always excluded, even if it also matches a whitelist rule. ### Trajectory Whitelist The whitelist defines which API paths are **allowed** to be tested for a given host. Only endpoints whose paths match the whitelist regex pattern will be included in the external assessment. Use the whitelist when you want to restrict testing to specific, known API areas. ### Trajectory Blacklist The blacklist defines which API paths must be **excluded** from testing. Any endpoint whose path matches a blacklist regex pattern will be completely ignored during the assessment, regardless of whether it matches a whitelist rule. **Important**: Blacklist rules always override whitelist rules. ### How to Configure Rules 1. Open **Settings -> Trajectories**. 2. **Under the Trajectory Whitelist Section, choose a host**: * Select an existing discovered host from the list, or * Choose **Select** **Custom Host** and enter the hostname manually. 3. **Add a rule**: * Enter a valid regex pattern for the path. * Click **Add rule**. 4. Repeat the process to add multiple rules for the same host or a different host. You can add rules to both the **Trajectory Whitelist** and **Trajectory Blacklist** sections independently. ### Common Regex Pattern Examples Here are useful patterns to get you started: ``` api/users — Matches the exact path /api/users /api/users/.* — Matches /api/users/ followed by anything (e.g., /api/users/123) ^/api/v[0-9]+/.* — Matches versioned API paths like /api/v1/, /api/v2/, etc. ^/api/(users|posts|comments)/.* — Matches specific resources: /api/users/…, /api/posts/…, or /api/comments/… ^/admin/.* — Matches all admin-related paths (useful for blacklisting) ^/(api|graphql)/.* — Matches both REST API and GraphQL endpoints .*\.(js|css|png|jpg|gif)$ — Matches static asset files (recommended for blacklisting) ``` ### Testing Your Rules (Examples Section) Before launching an external assessment, always verify your whitelist and blacklist configuration using the **Examples** testing area on the right side of the page. **How to test**: 1. Select a host from the dropdown. 2. View the list of currently discovered API endpoints. 3. Each endpoint will show whether it **passes** (included) or **fails** (excluded) based on your rules. 4. You can also enter custom paths to test them instantly. {% hint style="info" %} This step is crucial because the entire API testing scope depends on the correct whitelist and blacklist behaviour. Testing here helps catch misconfigured regex patterns early and prevents unintended inclusion or exclusion of endpoints. {% endhint %} # Download Agent Use **Settings -> Agent** to generate a short-lived deployment launcher for an internal assessment host. The launcher downloads the agent package, enrolls it with the control plane, and starts the agent. Generate it when the assessment host is ready. ## Supported Platforms * Windows * Linux * macOS Apple Silicon * macOS Intel ## Before Generating a Launcher Confirm: * written authorization and approved subnet scope; * the host is inside the target network or has a route to it; * endpoint protection and EDR allow the BugBase PCE Agent package, install directory, state directory, and process; * outbound HTTPS is allowed from the host to the RTCS URL and package download host; * the host can initiate assessment traffic to approved internal targets; * the operator has local administrator/root privileges where required. ## Generate and Run 1. Open **Settings -> Agent**. 2. Select the target platform. 3. Click **Generate Launcher**. 4. Copy or download the launcher. 5. Run it from an administrator/root shell on the assessment host. 6. Watch **Settings -> Agent** or **Dashboard -> Agents** until the agent appears connected. 7. Start internal discovery only after the agent is connected and reports the expected network information. ## Runtime Paths The UI shows expected install, state, log, temp/download, and process paths for the selected platform. Use those paths for EDR/AV allowlisting and cleanup planning. For Windows, the page also shows example Microsoft Defender commands for allowlisting the install path, state path, process, and self-signed code-signing certificate. ## Bootstrap Token The page exposes an admin bootstrap/master callback token for enrollment workflows. Treat it as sensitive. Rotate it when: * it was copied into the wrong place; * an operator leaves the engagement; * a launcher or token was exposed; * your security policy requires token rotation. Rotating the token invalidates the current bootstrap token. Existing enrolled agents are not affected. ## After the Engagement Plan cleanup before the scan: * stop and remove the agent where it is not needed for recurring assessments; * remove temporary files and logs according to your retention policy; * remove temporary EDR/AV allowlisting if it was engagement-specific; * rotate exposed credentials or tokens if they were copied outside approved storage. # Open-Source Edition Links for the open-source Pentest Copilot edition. The open-source Pentest Copilot project is a separate, human-in-the-loop research tool. This Enterprise documentation does not apply to its installation or operation. Use: * [GitHub repository](https://github.com/bugbasesecurity/pentest-copilot) for source code and releases; * [project wiki](https://github.com/bugbasesecurity/pentest-copilot/wiki) for installation and usage.