docs(slack): security reviews, threat model updates and credits in Slack

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.
+[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.
 
 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.
 
 ## Related docs
 

platform/slack-assistant.mdx

@@ -1,31 +1,33 @@
 ---
 title: "Hacktron in Slack"
-description: "Mention @Hacktron AI to triage findings, set up pentests and change PR review settings without leaving Slack."
+description: "Mention @Hacktron AI to ask security questions, triage findings, set up pentests and change PR review settings without leaving Slack."
 ---
 
-Mention **@Hacktron AI** in a Slack channel or direct message to work with your findings, set up a pentest or manage PR reviews. The assistant uses your Hacktron account and permissions, and replies in a thread.
+Mention **@Hacktron AI** in a Slack channel or direct message to ask security questions about your code and plans, work with your findings, set up a pentest or manage PR reviews. The assistant uses your Hacktron account and permissions, and replies in a thread.
 
 You can continue in that thread without mentioning it again. Teammates can join by mentioning @Hacktron AI. Each person's requests use their own account and permissions.
 
 ## What you can ask it to do
 
-| Task                                              | Example request                                                                      |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| [Look into findings](#ask-about-findings)         | How many critical findings are open in acme/api?                                     |
-| [Triage a finding](#act-on-findings-and-scans)    | Mark the SSRF finding in acme/api as a false positive because the URL is allowlisted |
-| [Set up a pentest](#set-up-a-pentest)             | Pentest acme/api on main and test staging.acme.com signed in                         |
-| [Manage PR reviews](#manage-pr-reviews)           | Turn on PR reviews for acme/api and acme/web                                         |
-| [Ask how Hacktron works](#ask-how-hacktron-works) | How do I stop reviews of PRs into release branches?                                  |
+| Task                                                           | Example request                                                                               |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [Ask a security question](#ask-security-questions)             | We're adding file uploads to acme/web. What should we think about?                            |
+| [Look into findings](#ask-about-findings)                      | How many critical findings are open in acme/api?                                              |
+| [Triage a finding](#act-on-findings-and-scans)                 | Mark the SSRF finding in acme/api as a false positive because the URL is allowlisted          |
+| [Update your threat model](#keep-your-threat-model-up-to-date) | Save our decision to fetch link previews through the egress proxy and update the threat model |
+| [Set up a pentest](#set-up-a-pentest)                          | Pentest acme/api on main and test staging.acme.com signed in                                  |
+| [Manage PR reviews](#manage-pr-reviews)                        | Turn on PR reviews for acme/api and acme/web                                                  |
+| [Ask how Hacktron works](#ask-how-hacktron-works)              | How do I stop reviews of PRs into release branches?                                           |
 
-Before changing a finding, stopping a scan or updating PR review settings, Hacktron shows you what will change and asks you to click **Approve**. Starting a pentest requires approval from an organization admin.
+Before changing a finding, stopping a scan, updating PR review settings or changing your threat model or context documents, Hacktron shows you what will change and asks you to click **Approve**. Starting a pentest requires approval from an organization admin.
 
 ## Set up
 
 <Steps>
   <Step title="Connect your workspace (organization admins)">
     In Hacktron, go to **Integrations** and find **Slack** under
     **Notifications**. Click **Connect**, then **Connect Slack** in the panel
     that opens. Approve the Hacktron AI app for your workspace to install it.
     See
     [Slack](/platform/communication-apps/slack) for the full steps.
 
@@ -42,9 +44,9 @@
 
   </Step>
   <Step title="Link your Slack account">
     In Hacktron, open **Personal settings**, find **Connected accounts** and click
     **Connect** next to **Slack**. Choose the workspace connected to your
     organization so Hacktron can match your Slack and Hacktron accounts. See [Link your Slack
     identity](/code-review/integrations/slack#link-your-slack-identity).
 
     <img
@@ -63,42 +65,81 @@
 
   </Step>
   <Step title="Send your first request">
     Mention **@Hacktron AI** with a request. The first time, Hacktron sends
     you a private **Connect Hacktron** message. Click the button, sign in to
     Hacktron and allow access. Hacktron waits for you to connect, then
     continues with your request in the thread.
   </Step>
 </Steps>
 
-Your Hacktron role determines what you can do. Viewers can ask questions, members can prepare pentests, and organization admins can start pentests and change PR review settings.
+Your Hacktron role determines what you can do. Viewers can ask questions. Members can also have Hacktron read your code, prepare pentests and update context documents and threat models. Organization admins can also start pentests, change PR review settings and manage applications.
 
 ## Ask about findings
 
 Ask in your own words, for example:
 
 - "How many critical findings are open in acme/api?"
 - "Show me the high severity findings from the last pentest"
 - "Which repositories have the most open findings?"
 
 Hacktron can return counts or post finding cards with links to the details in Hacktron.
 
 ## Act on findings and scans
 
 Ask Hacktron to change a finding's status, add a comment, stop a running scan or discard a pentest draft. Review the proposed change and click **Approve**. Hacktron confirms the result in the thread.
 
 Each finding card also has buttons to update its status or fix it with AI.
 
+## Ask security questions
+
+Think of Hacktron as a security engineer you can pull into any conversation. Ask about a feature you're planning, a design doc or PRD, how part of your app handles something like sign-in or file access, or a change you're about to ship.
+
+Hacktron answers from your own code and from what it already knows about your repositories. It can read the code at any branch or pull request, and it checks your threat models, context documents, recent pentests and past findings.
+
+A few things you might ask:
+
+- "We're adding file uploads to acme/web. What should we think about before we build it?"
+- "How does acme/api check that a user can see another team's projects?"
+- "Here's our PRD for shareable report links. What are we missing security-wise?" Paste the PRD into your message or attach it.
+- "Is `https://github.com/acme/api/pull/42` safe to merge?"
+
+Hacktron starts with the few points that matter most for what you're doing, and links each one to where it found it: a file and line, a related finding or your threat model. If something important is still unclear, it ends with a question for you. Reply in the thread to keep going.
+
+<img
+  src="/images/slack-assistant-security-review.png"
+  alt="Hacktron answering a security question in a Slack thread, citing lines of code and linking a related finding"
+/>
+
+Hacktron only calls something exploitable when the code shows it, so treat its points as things to check. To confirm one, ask Hacktron to [review the pull request](/code-review/overview) or [set up a pentest](#set-up-a-pentest).
+
+<Note>
+  Hacktron can read code from repositories connected through GitHub, GitLab and
+  Azure DevOps. The first question about a branch or pull request can take a
+  minute or two while Hacktron gets the code ready.
+</Note>
+
+## Keep your threat model up to date
+
+When a conversation settles something, ask Hacktron to save it. Your scans, PR reviews and later answers then take it into account. Before each change, Hacktron shows an **Approve** button that describes it.
+
+You can ask Hacktron to:
+
+- Save a decision, requirement, PRD or accepted risk from the thread as a [context document](/platform/context/overview#context-documents) on the repository.
+- Edit the [threat model](/platform/context/threat-models), for example to add a trust boundary. Your edits stay in place when the threat model updates later.
+- Update the threat model with new context documents and triage feedback. If a repository doesn't have a threat model yet, Hacktron builds one from the code. Updates run in the background and take a few minutes.
+- Create an [application](/platform/context/applications) from your repositories, add repositories to it or rebuild its threat model. Creating an application and adding repositories need an organization admin.
+
 ## Ask how Hacktron works
 
 Ask a product question, such as "How do I stop reviews of PRs into release branches?" Hacktron answers from the documentation and links to the relevant page. If the docs don't cover your question, it tells you.
 
 ## Manage PR reviews
 
 Ask Hacktron to turn PR reviews on or off for a repository. You can also change organization settings, including whether reviews post comments, which finding severity fails the PR check, and filters for target branches, labels, authors and title keywords.
 
 Anyone can ask to see the settings. Only organization admins can change them, after reviewing the change and clicking **Approve**.
 
 ## Set up a pentest
 
 <Steps>
   <Step title="Say what to test">
@@ -111,46 +152,55 @@
   </Step>
   <Step title="Add a live site (optional)">
     Provide a deployed app URL if you want live testing alongside the code
     review. Use a staging environment where possible. Without a URL, the pentest
     reviews the code only.
   </Step>
   <Step title="Confirm the cost">
     Hacktron estimates the pentest and asks you to confirm.
   </Step>
   <Step title="Start it">
     Hacktron posts an approval card. An organization admin clicks **Start
     pentest**. Credits are spent when the pentest starts.
   </Step>
   <Step title="Get the results">
     When the pentest finishes, Hacktron posts the results in the same thread.
   </Step>
 </Steps>
 
 ### Test a site signed in
 
 If the live site requires a login, click **Add login details** to open a private form. The form sends your details directly to Hacktron for encrypted storage. It keeps them out of the Slack thread and the assistant's conversation. Use this form rather than pasting credentials into Slack.
 
 Hacktron then checks that it can sign in and posts the result in the thread. If the check fails, click **Update login details** to fix them.
 
 A pentest uses the same access mode for all its live sites: signed in or without a login. To test both, create separate pentests.
 
 <Note>
   Signed-in testing must be enabled for your organization. If it isn't
   available, Hacktron lets you know. You can still test without signing in.
 </Note>
 
 ## Follow what it's doing
 
 A progress card at the top of the reply shows Hacktron's plan and the steps it takes.
 
+## Credits
+
+Replies from the Slack assistant use [automation credits](/platform/automations/credits) from your organization's balance. Pentests and fixes you start from Slack cost the same as when you start them in Hacktron.
+
+If your organization runs out of automation credits, Hacktron tells you in the thread and links to **Billing**. With auto top-up turned on, Hacktron buys more credits first.
+
 ## Limits
 
 - The Slack assistant can read attached archives, but it doesn't build or run your code. Provide a deployed app URL for live testing.
 - Each thread has a usage limit. When a thread reaches it, Hacktron stops and asks you to mention it in a new thread.
+- A conversation ends after a week without activity, and any files attached to it are deleted. To pick it back up, mention @Hacktron AI in the thread. It reads the thread again, but you need to attach files again.
+- Hacktron can't read code from Bitbucket repositories yet.
 - If Hacktron can't read an attachment, ask an organization admin to disconnect Slack and connect it again from **Integrations** to grant file access.
 
 ## Troubleshooting
 
 - **Hacktron doesn't reply to a mention in a channel.** Add it to the channel with `/invite @Hacktron AI`, and check that Slack is connected under **Integrations** in Hacktron.
 - **"Hacktron couldn't find your account for this workspace."** Link your Slack account from **Personal settings** > **Connected accounts** in Hacktron, choosing the same workspace, then try again.
+- **"Your Hacktron organization is out of automation credits."** An organization owner can buy credits from **Billing** or turn on [auto top-up](/platform/automations/credits#auto-top-up).
 - **Hacktron doesn't answer a reply in a thread.** If someone else started the thread, mention **@Hacktron AI** in your reply. Only the person who started it can continue without a mention.