docs: add a scheduled whitebox scans guide

docs.json

@@ -77,6 +77,7 @@
             "pages": [
               "platform/automations/overview",
               "platform/automations/remediation",
+              "platform/automations/scheduled-whitebox-scans",
               "platform/automations/credits"
             ]
           },

platform/automations/credits.mdx

@@ -3,9 +3,9 @@
 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.
 
 ## How credits work
 
@@ -24,7 +24,7 @@
     Complete any required card authentication (such as 3D Secure). The purchased credits are added to the organization balance after the charge succeeds.
   </Step>
   <Step title="Runs check the balance">
     A remediation run only starts while the organization has credits. When the balance runs out, new runs don't start and the Billing page shows that automations are paused.
   </Step>
   <Step title="Runs deduct on completion">
     Each run's cost is deducted from the balance once, when the run completes. Costs vary with the size of the run.
@@ -33,7 +33,7 @@
 
 ## Auto top-up
 
 Auto top-up buys credits automatically when the balance drops below a threshold, so your automations keep running without manual purchases.
 
 Set it up on the Billing page under your automation credit balance:
 
@@ -41,9 +41,9 @@
 - **Target**: the balance the top-up buys back up to. Your target must be above the trigger.
 - **Monthly limit**: an optional cap on how many credits auto top-up may buy per month.
 
 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
 

platform/automations/overview.mdx

@@ -1,77 +1,144 @@
 ---
-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**.
 
 <Tip>
-  **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.
 </Tip>
 
-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
 
 <Steps>
   <Step title="Create">
     On the **Automations** page, select **New automation** and give it a name.
 
-    ![New automation](/images/autofix-1.png)
-
+    <div className="block dark:hidden">
+
+  <Frame>
+    <img src="/images/new-automation-light.webp" alt="The New Automation dialog, asking for the automation's name" />
+  </Frame>
+</div>
+<div className="hidden dark:block">
+  <Frame>
+    <img src="/images/new-automation-dark.webp" alt="The New Automation dialog, asking for the automation's name" />
+  </Frame>
+</div>
   </Step>
   <Step title="Pick environments">
-    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.
+
+    <div className="block dark:hidden">
+
+  <Frame>
+    <img src="/images/automation-environments-light.webp" alt="The Environments tab, with a branch picker open for one repository" />
+  </Frame>
+</div>
+<div className="hidden dark:block">
+  <Frame>
+    <img src="/images/automation-environments-dark.webp" alt="The Environments tab, with a branch picker open for one repository" />
+  </Frame>
+</div>
   </Step>
   <Step title="Configure settings">
     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. |
+
+    <div className="block dark:hidden">
+
+  <Frame>
+    <img src="/images/automation-settings-light.webp" alt="The Settings tab with a trigger for Critical and High findings, an action, and a Slack notifier" />
+  </Frame>
+</div>
+<div className="hidden dark:block">
+  <Frame>
+    <img src="/images/automation-settings-dark.webp" alt="The Settings tab with a trigger for Critical and High findings, an action, and a Slack notifier" />
+  </Frame>
+</div>
   </Step>
   <Step title="Save">
-    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.
   </Step>
 </Steps>
 
 ## 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.
+
+<div className="block dark:hidden">
+  <Frame>
+    <img
+      src="/images/automation-run-history-light.webp"
+      alt="The Run history tab, with one running run and its trigger, environment, and credits spent"
+    />
+  </Frame>
+</div>
+<div className="hidden dark:block">
+  <Frame>
+    <img
+      src="/images/automation-run-history-dark.webp"
+      alt="The Run history tab, with one running run and its trigger, environment, and credits spent"
+    />
+  </Frame>
+</div>
 
 ## Related docs
 
 <Columns cols={2}>
-  <Card title="Remediation" icon="wrench" href="/platform/automations/remediation">
+  <Card
+    title="Remediation"
+    icon="wrench"
+    href="/platform/automations/remediation"
+  >
     How a remediation run works and where the fix lands.
   </Card>
-
-  <Card title="Automation credits" icon="coins" href="/platform/automations/credits">
-    How runs are billed and how to keep a balance with auto top-up.
+  <Card
+    title="Scheduled whitebox scans"
+    icon="calendar"
+    href="/platform/automations/scheduled-whitebox-scans"
+  >
+    Set a schedule and save the scan settings for each environment.
+  </Card>
+  <Card
+    title="Automation credits"
+    icon="coins"
+    href="/platform/automations/credits"
+  >
+    How remediation runs are billed and how auto top-up works.
   </Card>
 </Columns>

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.
+
+<Steps>
+  <Step title="Set the schedule">
+    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 *`.
+
+    <div className="block dark:hidden">
+
+  <Frame>
+    <img src="/images/automation-schedule-light.webp" alt="A weekly schedule at 02:00 UTC on the Settings tab, with its next three runs and the whitebox scan action" />
+  </Frame>
+</div>
+<div className="hidden dark:block">
+  <Frame>
+    <img src="/images/automation-schedule-dark.webp" alt="A weekly schedule at 02:00 UTC on the Settings tab, with its next three runs and the whitebox scan action" />
+  </Frame>
+</div>
+
+    Select **Save changes**.
+
+  </Step>
+  <Step title="Set up the scan for each environment">
+    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.
+
+  </Step>
+  <Step title="Turn the automation on">
+    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.
+
+  </Step>
+</Steps>
+
+## 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
+
+<Columns cols={2}>
+  <Card title="Automations" icon="bolt" href="/platform/automations/overview">
+    Configure triggers, actions, environments, and notifications.
+  </Card>
+  <Card
+    title="Credits and billing"
+    icon="credit-card"
+    href="/white-box-pentest/billing"
+  >
+    Check the Whitebox Scan balance and buy credits.
+  </Card>
+</Columns>

white-box-pentest/billing.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Credits and billing"
 description: "Understand Whitebox Scan credits, estimates, purchases, deductions, and refunds."
 ---
 
 Whitebox Scans use shared organization credits. A scan must have a completed or
 partial cost estimate with credits before it can start, and the organization
 needs enough credits for that estimate.
 
 <Info>
   Whitebox Scan credits are organization-wide. They are separate from Code
   Review seats, Automation credits, trials, and pooled PR/MR review limits.
 </Info>
 
@@ -16,12 +16,12 @@
 
 <Steps>
   <Step title="Calculate first">
     Hacktron calculates the credit cost from the selected repositories and
     scope. Cost calculation does not deduct credits.
   </Step>
   <Step title="Start with enough balance">
     Starting the scan deducts the calculated credits from the organization's
     Whitebox Scan credit balance. Internal unlimited organizations show
     unlimited credits and are not charged.
   </Step>
   <Step title="Track usage">
@@ -30,24 +30,32 @@
   </Step>
 </Steps>
 
+## 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
 without enough credits, Hacktron asks them to contact an owner to top up the
 balance.
 
 Whitebox Scan Credits do not use auto top-up. Owners purchase them manually without changing the organization's Automation credit balance or its auto top-up settings.
 
 Owners need a saved payment method before purchasing credits. If there is no
 payment method on file, the checkout flow prompts the owner to add one first,
 then opens the credit purchase modal.
 
 Organization owners can buy credits from **Billing** or from the Whitebox Scan
 checkout step when the organization does not have enough credits.
 
 <Steps>
   <Step title="Open Billing">
     Go to **Billing** in the Hacktron dashboard and find the Whitebox Scan
     credit balance.
   </Step>
   <Step title="Add a payment method">
@@ -59,7 +67,7 @@
     price.
   </Step>
   <Step title="Complete checkout">
     Complete any required card authentication. Hacktron adds the purchased
     credits to the organization balance after checkout succeeds.
   </Step>
 </Steps>
@@ -79,7 +87,7 @@
 3. Start the scan again after the balance covers the calculation.
 
 API callers receive `402 Payment Required` when a scan cannot start because the
 organization has insufficient Whitebox Scan credits.
 
 <Tip>
   The API does not buy credits automatically. Handle `402` by directing an
@@ -89,20 +97,20 @@
 
 ## Retests
 
 Each pentest includes **one free retest**, with no extra Whitebox Scan credits
 deducted. See [Retests](/white-box-pentest/retests) for how to request it.
 
 ## Refunds and cancellations
 
 If a started scan cannot launch successfully after credits are deducted,
 Hacktron attempts to refund those credits automatically. Failed and stopped
 scans can show refunded credits in the scan details and transaction history.
 
 ## Related docs
 
 <Columns cols={2}>
   <Card
     title="Trigger a Whitebox Scan"
     icon="shield-halved"
     href="/api-reference/scans/create-scan"
   >

white-box-pentest/quickstart.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Quickstart"
 description: "Prepare scope, estimate credits, and start a white-box pentest."
 ---
 
 Use this guide to prepare scope and start a White-box Pentest from the Hacktron
 dashboard.
 
 ## Prerequisites
@@ -11,10 +11,10 @@
 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
 - 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
 
 <Card
@@ -195,24 +195,27 @@
 | Authentication      | Test credentials, SSO notes, MFA bypass instructions, or invite steps.             |
 | Sensitive areas     | Auth, billing, permissions, file upload, webhooks, AI agents, or admin paths.      |
 | 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.            |
 
 ## 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
 to start the pentest.
 
 <Columns cols={2}>
   <Card title="Hacktron in Slack" icon="slack" href="/platform/slack-assistant">
     Mention @Hacktron AI with a repository or an attached archive.
   </Card>
   <Card title="MCP" icon="plug" href="/mcp/get-started">
     Set up pentests from Claude, Cursor, and other AI assistants.
   </Card>
   <Card
     title="Create pentest draft"
     icon="code"
     href="/api-reference/pentests/create-pentest"
   >