Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added images/whitebox_dynamic_testing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
81 changes: 68 additions & 13 deletions white-box-pentest/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,8 @@ Before you start, make sure the organization has:

- A connected repository or an uploaded archive to assess
- The branch or commit you want Hacktron to use
- Any target URLs that should be tested, such as staging or production URLs
- Authentication instructions for protected areas, if the application requires
sign-in
- For dynamic testing, the domains or URLs of the applications to test and
instructions for accessing each one, even if no sign-in is required
- Enough Whitebox Scan credits, or an organization owner who can add a payment
method and buy credits

Expand Down Expand Up @@ -47,13 +46,38 @@ On-premises deployments can select an enabled GitHub Enterprise Server repositor
<img src="/images/whitebox_select_repository.png" alt="Select the primary repository and branch for the scan" />

</Step>
<Step title="Add runtime context">
Add target URLs, login steps, test credentials, areas to emphasize, and any
exclusions. Keep credentials scoped to a test account where possible.
<Step title="Configure dynamic testing">
<Note>
**Dynamic testing is optional.** Choose **Skip dynamic testing** to
continue with a source-code assessment without testing a deployed
application.
</Note>

<img src="/images/whitebox_define_target.png" alt="Define target URLs and scope for the scan" />
In **Define target**, add each application you want Hacktron to test:

<img src="/images/whitebox_configure_access.png" alt="Configure access with login steps and test credentials" />
1. Enter its **Domain**, such as `https://staging.example.com`.
2. Fill in **Auth instructions** with login steps, dedicated test credentials,
and how to confirm successful access. For a public site, state that no
login is required and describe the page that should load.
3. Click **Verify access**. Hacktron follows your instructions in a browser;
a live access preview lets you watch the attempt. Wait for the target to
show **Verified** before continuing.

Use **Add target** for another application. Each target needs its own domain
and instructions. With multiple targets, **Verify all** checks the targets
that still need verification.

<img src="/images/whitebox_dynamic_testing.png" alt="Define target with a domain, public-site auth instructions, Verify access, Add target, and Skip dynamic testing" />

If verification fails, check the domain, credentials, and instructions, then
retry. Verification lasts for one hour. If you edit a verified target's
domain or instructions, verify it again or choose **Revert to last success**.

</Step>
<Step title="Add context and review scope">
In **Context documents**, add architecture notes, threat models, API specs,
or other material that helps explain the application. Then review the
repositories, targets, and access instructions in **Review details**.

</Step>
<Step title="Estimate the cost">
Expand Down Expand Up @@ -82,6 +106,42 @@ On-premises deployments can select an enabled GitHub Enterprise Server repositor
</Step>
</Steps>

## Writing auth instructions

Write instructions for each target as if someone were signing in for the first
time. Include:

- The starting URL and the steps to reach the application
- Test-account credentials and the role or permissions of each account
- How to obtain an MFA or OTP code, if required, and any SSO, CAPTCHA, or
network access requirements
- What successful access looks like, such as a dashboard or account page
- Areas to focus on and actions to avoid, such as payments or deleting data

For a target that requires sign-in:

```text
1. Open https://staging.example.com/login.
2. Sign in with qa-user@example.com and [dedicated test password].
3. Confirm the dashboard loads and the account has the Member role.
4. Focus on project access and file uploads.
5. Do not make payments, delete projects, or modify other users' data.
```

For a public target:

```text
1. Open https://help.example.com.
2. No login is required.
3. Confirm the help center and search page load.
```

<Warning>
Auth instructions are shared with AI agents for testing. Use a test
environment and dedicated test accounts, not personal credentials or
production secrets. Revoke test credentials after the assessment.
</Warning>

## Scope checklist

| Item | What to provide |
Expand All @@ -93,11 +153,6 @@ On-premises deployments can select an enabled GitHub Enterprise Server repositor
| Exclusions | Systems, data, tenants, destructive actions, or rate limits that are out of scope. |
| Context documents | Architecture notes, threat models, API specs, or prior pentest reports. |

<Warning>
Do not provide personal user credentials or production secrets. Use dedicated
test accounts and revoke them after the assessment.
</Warning>

## API option

You can also start Whitebox Scans from the REST API. The API follows the
Expand Down
Loading