diff --git a/docs.json b/docs.json index e2650a4..d754092 100644 --- a/docs.json +++ b/docs.json @@ -77,6 +77,7 @@ "pages": [ "platform/automations/overview", "platform/automations/remediation", + "platform/automations/scheduled-whitebox-scans", "platform/automations/credits" ] }, diff --git a/images/automation-environments-dark.webp b/images/automation-environments-dark.webp new file mode 100644 index 0000000..65bf1dd Binary files /dev/null and b/images/automation-environments-dark.webp differ diff --git a/images/automation-environments-light.webp b/images/automation-environments-light.webp new file mode 100644 index 0000000..9c9f17e Binary files /dev/null and b/images/automation-environments-light.webp differ diff --git a/images/automation-run-history-dark.webp b/images/automation-run-history-dark.webp new file mode 100644 index 0000000..6796f8b Binary files /dev/null and b/images/automation-run-history-dark.webp differ diff --git a/images/automation-run-history-light.webp b/images/automation-run-history-light.webp new file mode 100644 index 0000000..e905b68 Binary files /dev/null and b/images/automation-run-history-light.webp differ diff --git a/images/automation-schedule-dark.webp b/images/automation-schedule-dark.webp new file mode 100644 index 0000000..5d25740 Binary files /dev/null and b/images/automation-schedule-dark.webp differ diff --git a/images/automation-schedule-light.webp b/images/automation-schedule-light.webp new file mode 100644 index 0000000..c3d4653 Binary files /dev/null and b/images/automation-schedule-light.webp differ diff --git a/images/automation-settings-dark.webp b/images/automation-settings-dark.webp new file mode 100644 index 0000000..8932c24 Binary files /dev/null and b/images/automation-settings-dark.webp differ diff --git a/images/automation-settings-light.webp b/images/automation-settings-light.webp new file mode 100644 index 0000000..602f048 Binary files /dev/null and b/images/automation-settings-light.webp differ diff --git a/images/new-automation-dark.webp b/images/new-automation-dark.webp new file mode 100644 index 0000000..3ab0520 Binary files /dev/null and b/images/new-automation-dark.webp differ diff --git a/images/new-automation-light.webp b/images/new-automation-light.webp new file mode 100644 index 0000000..93924ec Binary files /dev/null and b/images/new-automation-light.webp differ diff --git a/platform/automations/credits.mdx b/platform/automations/credits.mdx index 15950a4..fea5489 100644 --- a/platform/automations/credits.mdx +++ b/platform/automations/credits.mdx @@ -3,7 +3,7 @@ title: "Automation credits" description: "Understand how to buy Automation credits, how runs use them, and how auto top-up works." --- -[Automations](/platform/automations/overview) run on shared organization automation credits. Every [remediation](/platform/automations/remediation) run, whether triggered manually from a finding or by an automation, deducts credits based on what the run costs when it completes. Replies from the [Slack assistant](/platform/slack-assistant#credits) use automation credits too. +[Remediation](/platform/automations/remediation) runs on shared organization automation credits. Every remediation run, whether you start it from a finding or an [automation](/platform/automations/overview) does, deducts credits based on what the run costs when it completes. [Scheduled whitebox scans](/platform/automations/scheduled-whitebox-scans) spend Whitebox Scan credits instead. Replies from the [Slack assistant](/platform/slack-assistant#credits) use automation credits too. Automation credits are organization-wide. They are separate from Code Review seats and your Whitebox Scan credits. @@ -43,7 +43,7 @@ Set it up on the Billing page under your automation credit balance: Auto top-up requires a saved payment method and charges the card on file without an interactive checkout. If a top-up charge fails, your automations stay paused until the balance is topped up manually or the card issue is resolved. -The Automation credits card on **Billing** shows the current balance, credits used in the billing period, auto top-up status, and a link to run history. Whitebox Scan Credits appear in a separate account and are never used for automation runs. +The Automation credits card on **Billing** shows the current balance, credits used in the billing period, auto top-up status, and a link to run history. Whitebox Scan Credits appear in a separate account and are never used for remediation runs. ## Related docs diff --git a/platform/automations/overview.mdx b/platform/automations/overview.mdx index 444e4b1..1a7ce60 100644 --- a/platform/automations/overview.mdx +++ b/platform/automations/overview.mdx @@ -1,17 +1,19 @@ --- -title: "Automations" -description: "Configure actions that run on triggers. Automate routine work such as remediation." +title: Automations +description: "Configure finding-triggered actions and scheduled whitebox scans." --- -Automations act for you. Configure the rules that qualify a match, and when one comes in, Hacktron fires the automation: its **actions** run, and **notifiers** alert your team over Slack or email. +An automation acts for you. It has one trigger: **New vulnerability found**, for new findings that match the rules you set, or [**On a schedule**](/platform/automations/scheduled-whitebox-scans), for the times you set. When the trigger fires, Hacktron runs the automation's **action**. - **Remediation** is the first available action. It starts a - [remediation](/platform/automations/remediation) run that fixes the finding, - and we'll expand automations with more actions over time. + Each trigger has its own action. **New vulnerability found** runs **Apply + Remediation**, which starts a [remediation](/platform/automations/remediation) + run that fixes the finding. **On a schedule** runs [**Start whitebox + scan**](/platform/automations/scheduled-whitebox-scans), which scans each + environment. -Automations live under **Automations** in the dashboard sidebar. Organization **Admins** create and manage automations; other members can view them. +Automations are under **Automations** in the dashboard sidebar. Organization **Admins** create and manage them, and other members can view them. ## Create an automation @@ -19,59 +21,124 @@ Automations live under **Automations** in the dashboard sidebar. Organization ** On the **Automations** page, select **New automation** and give it a name. - ![New automation](/images/autofix-1.png) - +
+ + + The New Automation dialog, asking for the automation's name + +
+
+ + The New Automation dialog, asking for the automation's name + +
 - Choose the repositories and [applications](/platform/context/applications) the automation covers. You can limit each entry to specific branches (up to two) or leave the branch selection empty to cover all branches. - - ![Pick environments](/images/autofix-2.png) - + Choose the repositories and [applications](/platform/context/applications) the automation covers. You can limit each entry to specific branches, up to two, or leave the branch selection empty to cover all branches. A scheduled automation takes its branches from each environment's [scan settings](/platform/automations/scheduled-whitebox-scans#create-a-scheduled-scan) instead. + +
+ + + The Environments tab, with a branch picker open for one repository + +
+
+ + The Environments tab, with a branch picker open for one repository + +
 On the **Settings** tab, set: - - **Triggers**: when the automation runs, for example a PR scan finding, it's narrowed by the rules you set, the severity levels that qualify, and scope rules that limit it to specific repositories or applications. - - **Actions**: what the automation does. **Remediation** starts a [remediation](/platform/automations/remediation) run for the matching finding. - - **Notifiers**: who hears about a run, whether it's a Slack channel, email recipients from your organization's members, or both. - - ![Configure settings](/images/autofix-3.png) - + | Setting | What it sets | + | --- | --- | + | **Triggers** | When the automation runs, added from **Add Trigger**. An automation has one trigger. **New vulnerability found** fires on a new finding, and **Add rule** limits it to the severity levels that qualify. [**On a schedule**](/platform/automations/scheduled-whitebox-scans) fires at the times you set. | + | **Actions** | What the automation does, added from **Add Action**. **Apply Remediation** starts a [remediation](/platform/automations/remediation) run for the matching finding. [**Start whitebox scan**](/platform/automations/scheduled-whitebox-scans) is only available with **On a schedule**, and **Apply Remediation** isn't available with it. | + | **Notifiers** | Who hears about a run: a Slack channel, email recipients from your organization's members, or both. | + +
+ + + The Settings tab with a trigger for Critical and High findings, an action, and a Slack notifier + +
+
+ + The Settings tab with a trigger for Critical and High findings, an action, and a Slack notifier + +
 - Select **Save**. An automation needs at least one environment, one trigger, and one action to run. Incomplete automations show an **Incomplete** badge and cannot be enabled. A save that removes required configuration disables the automation until it is complete again. + Select **Save changes**. An automation needs at least one environment, one trigger, and one action to run, and a scheduled automation also needs [scan settings for every environment](/platform/automations/scheduled-whitebox-scans#create-a-scheduled-scan). An incomplete automation shows an **Incomplete** badge and can't be enabled. A save that removes required configuration disables the automation until it is complete again. ## When an automation fires -When a new finding matches an enabled automation's trigger, severity rules, scope rules, and environment (including any branch limits), the automation fires: a **Remediation** action starts a remediation run, which uses [automation credits](/platform/automations/credits). After taking action, we send you a notification. +An automation with **New vulnerability found** fires when a new finding matches its severity rule and environment, including any branch limits, and the automation is enabled. **Apply Remediation** then starts a remediation run, which uses [automation credits](/platform/automations/credits). After the action, Hacktron sends a notification. -Each finding is fixed at most once, a finding that already has a remediation run won't fire automations again. +Each finding is fixed at most once. A finding that already has a remediation run doesn't fire automations again. ### Notifications -- **Slack**: Hacktron posts a message to your channel linking the finding. The Hacktron bot joins public channels automatically; for a private channel, invite the bot to the channel first. -- **Email**: Hacktron emails the recipients you choose from your organization's members. +In Slack, Hacktron posts a message to your channel with a link to the finding. The Hacktron bot joins public channels on its own. For a private channel, invite the bot first. -Notifications are best-effort, if one fails to send, it never blocks the remediation run itself. +By email, Hacktron writes to the recipients you chose from your organization's members. -## Run history +Notifications are best-effort. If one fails to send, the remediation run goes ahead. + +## Scheduled whitebox scans -The **Run history** tab lists every run your automation has fired, with its status, the environment it matched, and the credits it used. Runs matched through an application are attributed to that application. +Use **On a schedule** to repeat a whitebox scan of each configured environment. The [scheduled whitebox scans guide](/platform/automations/scheduled-whitebox-scans) covers the schedule, saved scan settings, login checks, and per-scan credit limits. -Run statuses mirror [remediation outcomes](/platform/automations/remediation#outcomes): **Running**, **Success**, **No fix needed**, **False positive**, and **Failed**. You can filter the history by status and search it. +## Run history -![Run history](/images/automation-run-history.png) +The **Run history** tab lists every run the automation has fired, with its status, the environment it matched, and the credits it used. A run matched through an application is attributed to that application. + +Run statuses follow the [remediation outcomes](/platform/automations/remediation#outcomes): **Running**, **Success**, **No fix needed**, **False positive**, **Fail**, and **Stopped**. You can filter the history by status and search it. + +[Scheduled scan runs](/platform/automations/scheduled-whitebox-scans#run-history) show scan progress, skipped scans, and any reason a scan needs attention. + +
+ + The Run history tab, with one running run and its trigger, environment, and credits spent + +
+
+ + The Run history tab, with one running run and its trigger, environment, and credits spent + +
## Related docs - + How a remediation run works and where the fix lands. - - - How runs are billed and how to keep a balance with auto top-up. + + Set a schedule and save the scan settings for each environment. + + + How remediation runs are billed and how auto top-up works. diff --git a/platform/automations/scheduled-whitebox-scans.mdx b/platform/automations/scheduled-whitebox-scans.mdx new file mode 100644 index 0000000..e63acbc --- /dev/null +++ b/platform/automations/scheduled-whitebox-scans.mdx @@ -0,0 +1,98 @@ +--- +title: "Scheduled whitebox scans" +description: "Schedule recurring whitebox scans with saved settings for each environment." +--- + +[Automations](/platform/automations/overview) can run whitebox scans on a schedule. Each environment has saved scan settings for its repositories, scope, targets, and credit limit. + +Organization **Admins** create and manage scheduled scans. Runs spend the organization's [Whitebox Scan credits](/white-box-pentest/billing). + +## Create a scheduled scan + +On **Automations**, select **New automation**, give it a name, and add the repositories or [applications](/platform/context/applications) to scan on the **Environments** tab. + +An automation with **On a schedule** runs a whitebox scan of each of its environments at the times you set. Adding the trigger sets the action to **Start whitebox scan**, which the **Settings** tab shows as **Start a whitebox scan for each configured environment**. Removing the trigger removes that action too. + + + + On the **Settings** tab, select **Add Trigger**, then **On a schedule**. A new schedule repeats weekly on Monday at 02:00, in your browser's timezone. Change it with these fields: + + | Field | What it sets | + | --- | --- | + | **Repeat** | **Daily**, **Weekly**, **Monthly**, or **Custom cron**. | + | **Time** | The time of day the scan starts. With **Custom cron**, the expression sets the time instead. | + | **Timezone** | The timezone the schedule follows, such as `UTC` or `Europe/London`. | + | **Days of the week** | With **Weekly**, the days to scan. | + | **Day of the month** | With **Monthly**, a day from 1 to 31. Months without that date are skipped. | + | **Cron expression** | With **Custom cron**, five fields: minute, hour, day of month, month, and day of week, in the selected timezone. | + + **Next three runs** lists the next three scan times, so you can check the schedule before you save it. A cron expression needs five fields and at least one future run. For quarterly scans at 02:00 on 1 January, 1 April, 1 July, and 1 October, use `0 2 1 1,4,7,10 *`. + +
+ + + A weekly schedule at 02:00 UTC on the Settings tab, with its next three runs and the whitebox scan action + +
+
+ + A weekly schedule at 02:00 UTC on the Settings tab, with its next three runs and the whitebox scan action + +
+ + Select **Save changes**. + + + + On the **Environments** tab, each environment now has **Set up scan** in place of the branch picker. Select it to open the environment's scan settings. They reuse the steps of the [Whitebox Scans wizard](/white-box-pentest/quickstart), with **Scan options** in place of the cost calculation and checkout: + + | Step | What it sets | + | --- | --- | + | **Select source** | The repositories to scan and the revision of each. For an application, these are its repositories. A branch uses its latest revision on each run. | + | **Scope** | Optional. The [paths to include and exclude](/white-box-pentest/quickstart#path-patterns) in each repository. | + | **Define targets** | Optional. The applications to test dynamically, with the login instructions for each. | + | **Context documents** | Optional. Documents that explain the application, and **Additional scan instructions**. | + | **Scan options** | **Model tier** (**Default** or **Legacy**) and **Max whitebox credits per scan**, a whole number from 1 to 1,000,000. | + | **Review details** | A summary of the other steps. | + + Select **Save scan settings**. Changes apply to future scans, and scans that have already started keep their settings. The environment's button then reads **Edit scan settings**. Only organization **Admins** can edit scan settings and login instructions. + + + + A scheduled automation can't be turned on until every environment has scan settings, and saving the schedule doesn't turn it on. Use the switch next to the automation's name. Once it's on, the automation's page shows the date and timezone of the next scan. + + Adding an environment without scan settings turns the automation off until you set up that environment's scan. + + + + +## Login checks + +Saved login instructions are checked before every scan. If the login fails, that scan doesn't start. To check them straight away, select **Save and check login** on the last step of the scan settings. The result shows on the **Define targets** and **Review details** steps, and the check appears in the [run history](#run-history) as **Login check**. + +If authenticated testing isn't enabled for your organization, Hacktron keeps the login instructions, but scans that need them can't start until it's enabled. + +## Credits and skipped scans + +Scheduled scans spend the organization's [Whitebox Scan credits](/white-box-pentest/billing). Each scan gets a fresh cost estimate. **Max whitebox credits per scan** includes the scan and any human triage it needs. A scan above that limit, or one the balance can't cover, doesn't start, and its run shows **Needs attention** with the reason. If the previous scan for an environment is still in progress when the next one is due, the next one is skipped. Missed scans are skipped too. + +## Run history + +Open the automation's **Run history** tab to see its runs, matched environments, status, and credits used. A scheduled scan's run opens the scan it started. + +While the scan is running, its row shows the stage: **Queued**, **Checking login**, **Estimating scope**, **Starting scan**, or **Scanning**. Scheduled runs can also end as **Needs attention** or **Skipped**. When a run records a reason, it shows under the status. + +## Related docs + + + + Configure triggers, actions, environments, and notifications. + + + Check the Whitebox Scan balance and buy credits. + + diff --git a/white-box-pentest/billing.mdx b/white-box-pentest/billing.mdx index b8adb4d..58ad751 100644 --- a/white-box-pentest/billing.mdx +++ b/white-box-pentest/billing.mdx @@ -30,6 +30,14 @@ needs enough credits for that estimate. +## Scheduled scans + +[Scheduled whitebox scans](/platform/automations/scheduled-whitebox-scans) +use this Whitebox Scan credit balance. Each run gets a fresh estimate. If the +estimate exceeds **Max whitebox credits per scan**, including any human triage, +or the balance cannot cover it, the scan does not start and its automation run +shows **Needs attention** with the reason. + ## Buy credits Organization owners can buy Whitebox Scan credits. If a member reaches checkout diff --git a/white-box-pentest/quickstart.mdx b/white-box-pentest/quickstart.mdx index 3690b04..00c1733 100644 --- a/white-box-pentest/quickstart.mdx +++ b/white-box-pentest/quickstart.mdx @@ -199,6 +199,9 @@ For a public target: ## Other ways to start a pentest +To repeat an assessment, [schedule whitebox scans](/platform/automations/scheduled-whitebox-scans) +and save the scan settings for each environment. + You can also prepare a pentest in Slack, through an AI assistant connected to Hacktron's MCP server, or through the REST API. Set the scope and review the credit estimate before starting. These options require an organization admin