diff --git a/api-reference/archives/request-archive-upload.mdx b/api-reference/archives/request-archive-upload.mdx index 11752e9..6377d69 100644 --- a/api-reference/archives/request-archive-upload.mdx +++ b/api-reference/archives/request-archive-upload.mdx @@ -4,17 +4,17 @@ openapi: "POST /archives/uploads" description: "Get a URL to upload a code archive to, for code that isn't in a connected repository." --- -Returns a signed URL to upload a `.zip`, `.7z` or `.tar.gz` archive of source code to. +Returns a signed URL for uploading a `.zip`, `.7z` or `.tar.gz` source archive. **Scope required**: `write`. **Role**: member or above. 1. Call this endpoint with the archive's `file_name`. 2. `PUT` the file to `upload_url`, with the `Content-Type` header set to the returned `content_type`. -3. Pentest it by adding `{ "source": "upload", "archive_id": "" }` to `repos` in [Create pentest draft](/api-reference/pentests/create-pentest). +3. Add `{ "source": "upload", "archive_id": "" }` to `repos` when you [create a pentest draft](/api-reference/pentests/create-pentest). -To pentest only part of the archive, set `include_paths` or `exclude_paths` on that repo instead of uploading a smaller archive. +To assess part of the archive, set `include_paths` or `exclude_paths` on its entry in `repos`. You can use the same uploaded archive. - Some self-hosted installs don't support uploads through the API and return - `400`. Upload the archive in the Hacktron web app instead. + Some self-hosted deployments return `400` because they don't support API + uploads. In that case, upload the archive through the Hacktron web app. diff --git a/api-reference/findings/count-findings.mdx b/api-reference/findings/count-findings.mdx index fc97010..a1ebdb2 100644 --- a/api-reference/findings/count-findings.mdx +++ b/api-reference/findings/count-findings.mdx @@ -4,6 +4,6 @@ openapi: "GET /findings/counts" description: "Count findings by severity, state and repository." --- -Counts the findings that match the same filters as [List findings](/api-reference/findings/list-findings), without paging through them. The response has the total, counts for every severity and state (zero when there are none), and counts per repository with the most findings first. +Counts findings using the same filters as [List findings](/api-reference/findings/list-findings), without requiring you to fetch every page. The response includes the total and counts by severity, state and repository. Severity and state counts include zero values. Repositories appear in order of finding count, highest first. **Scope required**: `read` diff --git a/api-reference/pentests/check-pentest-logins.mdx b/api-reference/pentests/check-pentest-logins.mdx index bd2d7c7..7417ccb 100644 --- a/api-reference/pentests/check-pentest-logins.mdx +++ b/api-reference/pentests/check-pentest-logins.mdx @@ -4,12 +4,14 @@ openapi: "POST /pentests/{id}/login-checks" description: "Check that Hacktron can sign in to each login target before the pentest starts." --- -Has Hacktron sign in to each of the draft's `login_targets` with its login instructions. Every login must pass before the pentest can start. +Checks whether Hacktron can sign in to each of the draft's `login_targets` using the saved login instructions. Every login check must pass before the pentest can start. **Scope required**: `write`. **Role**: member or above. -- A passed check lasts one hour. Start the pentest within the hour, or check again. -- Logins that are already being checked, or that passed within the last hour, aren't checked again unless their site or login instructions changed. -- Set `wait_seconds` (up to 50) to wait for the checks to finish before the response returns. Without it, the response returns while the checks are `pending`. Call again with `wait_seconds` to wait for them. Each call checks failed logins again, so fix their instructions first. +- A successful check is valid for one hour. Start the pentest within that time or run the check again. +- Hacktron skips checks that are already running or passed within the last hour, unless the site or login instructions have changed. +- Set `wait_seconds` to wait up to 50 seconds for the checks. Without it, the endpoint returns while checks are `pending`. You can call again with `wait_seconds` to wait for the results. Each call retries failed logins, so update incorrect instructions before calling again. -Each entry in `login_targets` reports its `login_check`: `pending` or `running` while Hacktron signs in, `succeeded` when it signed in, and `failed` when it couldn't. A failed check has a `failure_reason`, which never includes the login details. Fix the instructions with [Update pentest draft](/api-reference/pentests/update-pentest) and check again. +Each entry in `login_targets` includes a `login_check` status: `pending` or `running` while the check is in progress, `succeeded` after a successful sign-in, or `failed` if Hacktron couldn't sign in. + +A failed check includes a `failure_reason` without login details. Correct the instructions with [Update pentest draft](/api-reference/pentests/update-pentest), then run the check again. diff --git a/api-reference/pentests/create-pentest.mdx b/api-reference/pentests/create-pentest.mdx index 434bb58..80c0f90 100644 --- a/api-reference/pentests/create-pentest.mdx +++ b/api-reference/pentests/create-pentest.mdx @@ -4,18 +4,18 @@ openapi: "POST /pentests" description: "Create a pentest that hasn't started, from repositories or uploaded archives, optionally with live sites." --- -Creates a draft pentest. A draft holds the code to review and, optionally, deployed sites to test live. Nothing runs and no credits are spent until you [start it](/api-reference/pentests/start-pentest). +Creates a draft with the code you want to review and any deployed sites you want to test. Creating a draft does not run a pentest or spend credits. You review the estimate before [starting it](/api-reference/pentests/start-pentest). **Scope required**: `write`. **Role**: member or above. -## Lifecycle +## Set up and start a pentest 1. Create the draft with this endpoint, and change it with [Update pentest draft](/api-reference/pentests/update-pentest). 2. If the draft has `login_targets`, run [Check pentest logins](/api-reference/pentests/check-pentest-logins) until each login passes. -3. Price it with [Estimate pentest](/api-reference/pentests/estimate-pentest). +3. Get the credit cost with [Estimate pentest](/api-reference/pentests/estimate-pentest). 4. Start it with [Start pentest](/api-reference/pentests/start-pentest), or delete it with [Discard pentest draft](/api-reference/pentests/discard-pentest). -Keep the `scan_id` from the response. It identifies the pentest from draft to finish, so you can follow it afterwards with [Get scan](/api-reference/scans/get-scan). +Save the `scan_id` from the response. Use the same ID throughout setup and after the pentest starts, including when calling [Get scan](/api-reference/scans/get-scan). ## What to test @@ -23,7 +23,7 @@ Keep the `scan_id` from the response. It identifies the pentest from draft to fi - `target_urls`: deployed sites to test without signing in. - `login_targets`: deployed sites to test signed in. Each has a `site` and `login_instructions`: the login page, username, password and any extra steps. Login instructions are stored encrypted and never returned. -A pentest tests its live sites either all signed in or all without a login, so one draft can't have both `target_urls` and `login_targets`. Create a separate pentest for the other kind. +A draft can have `target_urls` or `login_targets`, but not both. To test sites with and without a login, create separate pentests. Signed-in testing is enabled per organization. If it isn't enabled for yours, diff --git a/api-reference/pentests/estimate-pentest.mdx b/api-reference/pentests/estimate-pentest.mdx index a6734de..a880967 100644 --- a/api-reference/pentests/estimate-pentest.mdx +++ b/api-reference/pentests/estimate-pentest.mdx @@ -8,6 +8,6 @@ Starts a cost estimation for the draft and returns its `cost_estimation_id`. Pol **Scope required**: `write`. **Role**: member or above. -The total to confirm when you [start the pentest](/api-reference/pentests/start-pentest) is the estimate's `total_credits`, plus `triage_fee_credits` when `triage_required` is true or you opt in to triage. +When you [start the pentest](/api-reference/pentests/start-pentest), confirm the estimate's `total_credits`. Add `triage_fee_credits` if `triage_required` is true or you opt in to triage. Estimate again whenever you change the draft. diff --git a/api-reference/pentests/start-pentest.mdx b/api-reference/pentests/start-pentest.mdx index b687fa5..6efa2b9 100644 --- a/api-reference/pentests/start-pentest.mdx +++ b/api-reference/pentests/start-pentest.mdx @@ -8,7 +8,7 @@ Starts a draft pentest that has a completed estimate. Credits are deducted when **Scope required**: `write`. **Role**: organization admin. -- `expected_credits` is the total you confirmed: the estimate's `total_credits`, plus `triage_fee_credits` when triage is required or you set `triage_enabled`. If the pentest now costs a different amount, the request fails with `409` and nothing is spent. Without enough credits it fails with `402`. +- Set `expected_credits` to the estimate's `total_credits`, plus `triage_fee_credits` if triage is required or you set `triage_enabled`. If the current cost differs from this total, the endpoint returns `409` without spending credits. If the organization has insufficient credits, it returns `402`. - Every login target needs a login check that passed within the last hour. See [Check pentest logins](/api-reference/pentests/check-pentest-logins). After it starts, follow the pentest with [Get scan status](/api-reference/scans/get-scan-status) using the same `scan_id`, read its results with [List scan findings](/api-reference/scans/list-scan-findings), or stop it with [Stop scan](/api-reference/scans/stop-scan). diff --git a/api-reference/pentests/update-pentest.mdx b/api-reference/pentests/update-pentest.mdx index a0e1fbe..db00939 100644 --- a/api-reference/pentests/update-pentest.mdx +++ b/api-reference/pentests/update-pentest.mdx @@ -4,13 +4,13 @@ openapi: "PATCH /pentests/{id}" description: "Change a pentest that hasn't started." --- -Changes a draft pentest. Fields you send replace the saved values, and fields you leave out are kept. A pentest that has started can't be changed. +Updates a draft pentest. Fields in the request replace their saved values; omitted fields keep their current values. You can't change a pentest after it starts. **Scope required**: `write`. **Role**: member or above. -- `repos` replaces the saved repositories and needs at least one. Changing them clears the estimate. -- `login_targets` replaces the whole list, and `[]` removes every login target. Resending a site with the same login instructions keeps its passed login check. A changed site or login reports `login_check: unverified` until you check it again. +- `repos` replaces the saved repository list and must contain at least one entry. Changing it clears the estimate. +- `login_targets` replaces the full list. Send `[]` to remove all login targets. Sending the same site and login instructions preserves a successful login check. Changing either resets `login_check` to `unverified` until you check again. - To fix a login that failed its check, send the site again with new `login_instructions`, then run [Check pentest logins](/api-reference/pentests/check-pentest-logins). - To switch a draft from signed-in testing to testing without a login (or back), clear the other list in the same request, for example `"login_targets": []` with your `target_urls`. -Estimate the pentest again after changing it. [Start pentest](/api-reference/pentests/start-pentest) rejects a total that doesn't match the current estimate. +Run the estimate again after changing the draft. [Start pentest](/api-reference/pentests/start-pentest) rejects a credit total that doesn't match the current estimate. diff --git a/api-reference/repos/get-pr-review-settings.mdx b/api-reference/repos/get-pr-review-settings.mdx index a910817..471b857 100644 --- a/api-reference/repos/get-pr-review-settings.mdx +++ b/api-reference/repos/get-pr-review-settings.mdx @@ -4,13 +4,13 @@ openapi: "GET /pr-review-settings" description: "Read how PR reviews behave across your organization." --- -Returns your organization's PR review settings, the ones under **Settings** in Hacktron: +Returns the PR review settings configured for your organization under **Settings** in Hacktron: - `scm_comments_enabled`: reviews post comments and finding details on pull and merge requests. - `scm_system_comments_enabled`: reviews also post system comments, such as skipped reviews, usage limits and configuration warnings. - `fail_on_severity`: the severity at or above which a finding fails the PR check, or `null` when it never fails. - `scan_include_*` and `scan_exclude_*`: which pull requests are reviewed, by target branch, label, author and title keyword. `null` means no filter. -A repository's [`.hacktron/config.yaml`](/code-review/config) overrides these. Whether each repository has reviews turned on is `prScansEnabled` in [List repositories](/api-reference/repos/list-repos). +A repository's [`.hacktron/config.yaml`](/code-review/config) takes precedence over these defaults. To check whether reviews are enabled for a repository, read its `prScansEnabled` value from [List repositories](/api-reference/repos/list-repos). **Scope required**: `read` diff --git a/api-reference/repos/set-pr-reviews.mdx b/api-reference/repos/set-pr-reviews.mdx index 88f59bb..b8e7a14 100644 --- a/api-reference/repos/set-pr-reviews.mdx +++ b/api-reference/repos/set-pr-reviews.mdx @@ -4,10 +4,10 @@ openapi: "POST /repos/pr-reviews" description: "Turn automatic pull and merge request reviews on or off for repositories." --- -Turns automatic PR and MR reviews on for the repositories in `enable` and off for those in `disable`. Use each repository's `id` from [List repositories](/api-reference/repos/list-repos), whichever provider it's on. Up to 100 of each per request. +Enables automatic pull and merge request reviews for repositories in `enable` and disables them for repositories in `disable`. Use repository IDs from [List repositories](/api-reference/repos/list-repos) for any supported provider. Each list can contain up to 100 IDs per request. **Scope required**: `write`. **Role**: organization admin. -- A repository must be enabled for Hacktron access before its reviews can be turned on. Enable it from **Repositories** in Hacktron. -- One repository failing doesn't stop the rest. The response counts the repositories that changed (`processed`) and lists each one that didn't with the reason (`failedRepositories`). -- `webhookPending` lists repositories that were turned on but whose provider webhook couldn't be registered yet. Reviews start once it is. +- First, enable Hacktron access to the repository from **Repositories** in Hacktron. +- If one repository fails, Hacktron continues with the others. The response reports how many changed in `processed` and lists failures with their reasons in `failedRepositories`. +- `webhookPending` lists enabled repositories whose provider webhook is still pending registration. Reviews begin once the webhook is registered. diff --git a/api-reference/repos/update-pr-review-settings.mdx b/api-reference/repos/update-pr-review-settings.mdx index 6cb5acb..9aeb933 100644 --- a/api-reference/repos/update-pr-review-settings.mdx +++ b/api-reference/repos/update-pr-review-settings.mdx @@ -4,10 +4,10 @@ openapi: "PATCH /pr-review-settings" description: "Change how PR reviews behave across your organization." --- -Changes your organization's PR review settings and returns all of them. Only the fields you send change. Send `null` to turn off `fail_on_severity` or clear a filter. +Updates your organization's PR review settings and returns the full settings object. Only fields in the request change. Send `null` to disable `fail_on_severity` or clear a filter. **Scope required**: `write`. **Role**: organization admin. -A filter is replaced as a whole. To add one branch, read the settings with [Get PR review settings](/api-reference/repos/get-pr-review-settings) first and send the full list. +Each filter replaces the saved list. To add a branch without removing existing entries, first read [Get PR review settings](/api-reference/repos/get-pr-review-settings), then send the full list with your addition. Branch and author filters take glob patterns (`*`, `**`, `?`, `{a,b}`) and are case-insensitive. Each filter holds up to 50 entries. diff --git a/api-reference/scans/stop-scan.mdx b/api-reference/scans/stop-scan.mdx index db86295..b28c2c9 100644 --- a/api-reference/scans/stop-scan.mdx +++ b/api-reference/scans/stop-scan.mdx @@ -4,6 +4,6 @@ openapi: "POST /scans/{id}/stop" description: "Stop a running scan or pentest." --- -Stops a scan that is running and returns its status. Members can stop pentests they started and any PR scan, and organization admins can stop any scan. +Stops a running scan and returns its status. Members can stop their own pentests and any PR scan. Organization admins can stop any scan. **Scope required**: `write`. **Role**: member or above. diff --git a/code-review/integrations/slack.mdx b/code-review/integrations/slack.mdx index 338b892..8045011 100644 --- a/code-review/integrations/slack.mdx +++ b/code-review/integrations/slack.mdx @@ -61,7 +61,7 @@ so that Hacktron can recognize you on Slack. -You can now provide feedback and act on findings directly from Slack, and [ask Hacktron in Slack](/platform/communication-apps/slack-agent) as yourself. +You can now provide feedback and update findings from Slack. To ask about findings, prepare a pentest or manage PR reviews, [mention @Hacktron AI](/platform/slack-assistant). - Create an organization API key — see [Authentication](/api-reference/authentication#creating-an-api-key). Grant `read` & `write` access to let your assistant triage findings. + Create an organization API key using the [Authentication guide](/api-reference/authentication#creating-an-api-key). Grant `read` and `write` access if you want your assistant to triage findings. Run in terminal: @@ -53,7 +53,7 @@ description: "Choose your platform and copy the config. No API key required." When Claude Desktop connects to Hacktron for the first time, complete the Hacktron browser sign-in. If the prompt does not appear, open Claude Desktop's MCP server settings and reconnect `hacktron`. - Create an organization API key — see [Authentication](/api-reference/authentication#creating-an-api-key). Grant `read` & `write` access to let your assistant triage findings. + Create an organization API key using the [Authentication guide](/api-reference/authentication#creating-an-api-key). Grant `read` and `write` access if you want your assistant to triage findings. ```json { @@ -91,7 +91,7 @@ description: "Choose your platform and copy the config. No API key required." When Cursor prompts you to authenticate `hacktron`, complete the Hacktron browser sign-in. You can also open Cursor's MCP settings, select `hacktron`, and start authentication from there. - Create an organization API key — see [Authentication](/api-reference/authentication#creating-an-api-key). Grant `read` & `write` access to let your assistant triage findings. + Create an organization API key using the [Authentication guide](/api-reference/authentication#creating-an-api-key). Grant `read` and `write` access if you want your assistant to triage findings. ```json { @@ -129,7 +129,7 @@ description: "Choose your platform and copy the config. No API key required." Complete the Hacktron browser sign-in. In an interactive Codex session, type `/mcp` to check the server's connection and authentication status. - Create an organization API key — see [Authentication](/api-reference/authentication#creating-an-api-key). Grant `read` & `write` access to let your assistant triage findings. + Create an organization API key using the [Authentication guide](/api-reference/authentication#creating-an-api-key). Grant `read` and `write` access if you want your assistant to triage findings. **1.** Add your API key to your shell profile (`~/.zshrc` or `~/.bashrc`): @@ -172,17 +172,19 @@ description: "Choose your platform and copy the config. No API key required." ## Tools -Each tool calls the same endpoint as the [REST API](/api-reference/introduction), with the same permissions. Viewers can read, members can change findings and set up pentests, and only organization admins can start a pentest. +Use these tools to work with Hacktron from your AI assistant. The linked [REST API endpoints](/api-reference/introduction) provide the same operations and permission requirements. + +Viewers can read scans and findings. Members can update findings and prepare pentests. Starting a pentest or changing PR review settings requires an organization admin. ### Scans and findings | Name | Description | REST endpoint | | --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ | -| `list_scans` | List scans with severity breakdown | [`GET /scans`](/api-reference/scans/list-scans) | +| `list_scans` | List scans with finding counts by severity | [`GET /scans`](/api-reference/scans/list-scans) | | `get_scan` | Get details about a scan | [`GET /scans/{id}`](/api-reference/scans/get-scan) | | `export_findings` | Export a scan's findings as JSON, CSV, or SARIF | [`GET /scans/{id}/findings/export`](/api-reference/scans/export-scan-findings) | | `stop_scan` | Stop a running scan or pentest | [`POST /scans/{id}/stop`](/api-reference/scans/stop-scan) | -| `list_findings` | List findings across the organisation | [`GET /findings`](/api-reference/findings/list-findings) | +| `list_findings` | List findings across your organization | [`GET /findings`](/api-reference/findings/list-findings) | | `count_findings` | Count findings by severity, state and repository | [`GET /findings/counts`](/api-reference/findings/count-findings) | | `get_finding` | Get details about a finding | [`GET /findings/{id}`](/api-reference/findings/get-finding) | | `update_finding` | Update a finding's state or severity | [`PATCH /findings/{id}`](/api-reference/findings/update-finding) | @@ -190,31 +192,31 @@ Each tool calls the same endpoint as the [REST API](/api-reference/introduction) ### Pentests -| Name | Description | REST endpoint | -| ------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `list_repositories` | List connected repositories | [`GET /repos`](/api-reference/repos/list-repos) | -| `request_archive_upload` | Get a URL to upload a code archive | [`POST /archives/uploads`](/api-reference/archives/request-archive-upload) | -| `create_pentest_draft` | Set up a pentest of code, optionally with live sites | [`POST /pentests`](/api-reference/pentests/create-pentest) | -| `update_pentest_draft` | Change a pentest that hasn't started | [`PATCH /pentests/{id}`](/api-reference/pentests/update-pentest) | -| `verify_pentest_login` | Check that Hacktron can sign in to each site | [`POST /pentests/{id}/login-checks`](/api-reference/pentests/check-pentest-logins) | -| `estimate_pentest` | Price a pentest | [`POST /pentests/{id}/estimate`](/api-reference/pentests/estimate-pentest) | -| `get_cost_estimation` | Get a pentest cost estimate | [`GET /cost-estimations/{id}`](/api-reference/cost-estimations/get-cost-estimation) | -| `get_credit_balance` | Get the organisation's pentest credit balance | [`GET /credits`](/api-reference/credits/get-credit-balance) | -| `start_pentest` | Start a pentest and spend its credits (admins only) | [`POST /pentests/{id}/start`](/api-reference/pentests/start-pentest) | -| `discard_pentest_draft` | Delete a pentest that hasn't started | [`DELETE /pentests/{id}`](/api-reference/pentests/discard-pentest) | +| Name | Description | REST endpoint | +| ------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `list_repositories` | List connected repositories | [`GET /repos`](/api-reference/repos/list-repos) | +| `request_archive_upload` | Get a URL to upload a code archive | [`POST /archives/uploads`](/api-reference/archives/request-archive-upload) | +| `create_pentest_draft` | Create a draft with code and optional live sites | [`POST /pentests`](/api-reference/pentests/create-pentest) | +| `update_pentest_draft` | Change a pentest that hasn't started | [`PATCH /pentests/{id}`](/api-reference/pentests/update-pentest) | +| `verify_pentest_login` | Check that Hacktron can sign in to each site | [`POST /pentests/{id}/login-checks`](/api-reference/pentests/check-pentest-logins) | +| `estimate_pentest` | Estimate a draft pentest's credit cost | [`POST /pentests/{id}/estimate`](/api-reference/pentests/estimate-pentest) | +| `get_cost_estimation` | Get a pentest cost estimate | [`GET /cost-estimations/{id}`](/api-reference/cost-estimations/get-cost-estimation) | +| `get_credit_balance` | Read your organization's pentest credit balance | [`GET /credits`](/api-reference/credits/get-credit-balance) | +| `start_pentest` | Start a pentest and spend its credits (admins only) | [`POST /pentests/{id}/start`](/api-reference/pentests/start-pentest) | +| `discard_pentest_draft` | Delete a pentest that hasn't started | [`DELETE /pentests/{id}`](/api-reference/pentests/discard-pentest) | ### PR reviews -| Name | Description | REST endpoint | -| --------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `get_pr_review_settings` | Get how PR reviews behave across the organisation | [`GET /pr-review-settings`](/api-reference/repos/get-pr-review-settings) | -| `update_pr_review_settings` | Change PR review comments, fail-on severity and filters (admins only) | [`PATCH /pr-review-settings`](/api-reference/repos/update-pr-review-settings) | -| `set_pr_reviews` | Turn PR reviews on or off for repositories (admins only) | [`POST /repos/pr-reviews`](/api-reference/repos/set-pr-reviews) | +| Name | Description | REST endpoint | +| --------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| `get_pr_review_settings` | Read your organization's PR review settings | [`GET /pr-review-settings`](/api-reference/repos/get-pr-review-settings) | +| `update_pr_review_settings` | Update review comments, the check's severity threshold and filters (admins only) | [`PATCH /pr-review-settings`](/api-reference/repos/update-pr-review-settings) | +| `set_pr_reviews` | Turn PR reviews on or off for repositories (admins only) | [`POST /repos/pr-reviews`](/api-reference/repos/set-pr-reviews) | - To test a site signed in, your assistant sends the login details to Hacktron, - where they're stored encrypted. Anything you type in the conversation also - goes to your assistant's model provider, so use a test account. + For signed-in testing, your assistant sends login details to Hacktron for + encrypted storage. Anything you type in the conversation also goes to your + assistant's model provider. Use dedicated test credentials. ## Related @@ -225,9 +227,9 @@ Each tool calls the same endpoint as the [REST API](/api-reference/introduction) icon="key" href="/api-reference/authentication" > - Create and scope the API key used for API-key auth. + Create an API key and choose its access scopes. - Every tool, over the REST API. + Use the same operations from your own scripts and applications. diff --git a/platform/communication-apps/slack-agent.mdx b/platform/communication-apps/slack-agent.mdx deleted file mode 100644 index b30db01..0000000 --- a/platform/communication-apps/slack-agent.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: "Ask Hacktron in Slack" -description: "Mention @Hacktron AI to ask about findings, set up pentests and manage PR reviews from Slack." ---- - -Mention **@Hacktron AI** in a channel, or send it a direct message, to ask about your scans and findings, set up a pentest, turn PR reviews on or off, or ask how Hacktron works. It replies in a thread. Keep talking in that thread without mentioning it again. Teammates can join the thread by mentioning @Hacktron AI, and it acts for each person with their own access. - -## Set up - - - - In Hacktron, go to **Integrations**, find **Slack** under **Communication - Apps** and click **Connect**. Approve the Hacktron AI app for your - workspace. This installs the app in Slack. See - [Slack](/platform/communication-apps/slack) for the full steps. - - - If your organization connected Slack before Hacktron could read files, - click **Connect** again so Hacktron can read archives people attach. - - - - - In Hacktron, open **Account**, scroll to **Connected Accounts** and click - **Connect** next to **Slack**. Choose the same workspace. This is how - Hacktron knows who's asking. See [Link your Slack - identity](/code-review/integrations/slack#link-your-slack-identity). - - - In Slack, open the channel and send `/invite @Hacktron AI`. You can also - click the channel name, open **Integrations** and click **Add apps**. This - works for public and private channels. - - To talk to it privately instead, find **Hacktron AI** under **Apps** in - the Slack sidebar and send it a message. - - - - Mention **@Hacktron AI** with a question. The first time, Hacktron sends - you a private **Connect Hacktron** message that only you can see. Click - it, sign in to Hacktron and allow access. The thread says it's waiting for - you, then Hacktron carries on with your question. - - - -Hacktron acts as you, with your role: viewers can ask questions, members can set up pentests, and organization admins can start them and change settings. - -## 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 answers with counts and posts findings as cards that link to them in Hacktron. - -## Ask how Hacktron works - -Ask a question about the product, such as "How do I stop reviews of PRs into release branches?". Hacktron answers from these docs and links the page it used. When the docs don't cover it, it says so. - -## Manage PR reviews - -Ask Hacktron to turn PR reviews on or off for a repository, or to change how they behave across your organization: whether they comment on pull requests, the severity that fails the PR check, and which branches, labels, authors or title keywords get reviewed. Anyone can ask what the settings are. Only organization admins can change them, and Hacktron shows an **Approve** button before it does. - -## Set up a pentest - - - - Name a connected repository, or attach a `.zip`, `.7z` or `.tar.gz` archive - of the code (up to 2 GB) to your message. - - - To test only part of the code, say so in the thread, for example "only the - services/payments folder". There's no need to upload a smaller archive. - - - Give Hacktron the URL of a deployed copy of the app to test it live as well - as the code. A staging copy is the safest choice. Without one, the pentest - reviews the code only. - - - Hacktron estimates the pentest and asks you to confirm. - - - Hacktron posts an approval card. An organization admin clicks **Start - pentest**. Credits are spent when the pentest starts. - - - When the pentest finishes, Hacktron posts the results in the same thread. - - - -### Test a site signed in - -If the live site needs a login, Hacktron posts an **Add login details** button. It opens a private form that only you can see. The details go straight to Hacktron, are stored encrypted, and never appear in the thread or reach the assistant. - -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 tests its live sites either all signed in or all without a login. To test both kinds, set up a separate pentest for each. - - - Signed-in testing is enabled per organization. If it isn't available for - yours, Hacktron says so and can still test the site without signing in. - - -## Follow what it's doing - -While it works, Hacktron shows its plan and each step it takes in a progress card at the top of its reply. - -## Limits - -- Hacktron reads attached archives to understand the code, but never runs your code. To test the running app, give it a deployed site. -- Each thread has a usage limit. When a thread reaches it, Hacktron stops and asks you to mention it in a new thread. -- If Hacktron can't read files you attach, ask an organization admin to reconnect Slack from **Integrations** so the app gets permission to read files. - -## 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 **Account** > **Connected Accounts** in Hacktron, choosing the same workspace, then try again. -- **A reply without a mention gets no answer.** Only the person who started the thread can reply without mentioning Hacktron. Everyone else mentions **@Hacktron AI** in the thread. diff --git a/platform/communication-apps/slack.mdx b/platform/communication-apps/slack.mdx index a369fd8..7f28de5 100644 --- a/platform/communication-apps/slack.mdx +++ b/platform/communication-apps/slack.mdx @@ -28,8 +28,8 @@ You also need permission to authorize apps in the Slack workspace you want Hackt Hacktron uses this access to send security notifications and scan updates - to the Slack channel you configure, and to answer people who mention - @Hacktron AI. + to your configured channel. It also lets people work with Hacktron by + mentioning @Hacktron AI. @@ -62,14 +62,11 @@ Open the Slack card in **Integrations** and choose **Disconnect**. Hacktron will - If a channel is missing, confirm that the Slack workspace account used for OAuth can access that channel. - If notifications are not appearing, confirm that the Slack integration is connected and a channel is selected. -## Next: ask Hacktron in Slack +## Next: use Hacktron in Slack -Connecting Slack installs the Hacktron AI app in your workspace. To let people ask it questions, set up pentests and manage PR reviews, add it to channels with `/invite @Hacktron AI` and have each person link their Slack account. +Connecting Slack installs the Hacktron AI app in your workspace. Add it to a channel with `/invite @Hacktron AI`. Each person then links their Slack and Hacktron accounts to use the assistant with their own permissions. - - Set up and use @Hacktron AI in your channels. + + Triage findings, set up pentests and manage PR reviews by mentioning @Hacktron + AI. diff --git a/platform/slack-assistant.mdx b/platform/slack-assistant.mdx new file mode 100644 index 0000000..1201a77 --- /dev/null +++ b/platform/slack-assistant.mdx @@ -0,0 +1,149 @@ +--- +title: "Hacktron in Slack" +description: "Mention @Hacktron AI to 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. + +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? | + +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. + +## Set up + + + + In Hacktron, go to **Integrations**, find **Slack** under **Communication + Apps** and click **Connect**. Approve the Hacktron AI app for your + workspace. This installs the app in Slack. See + [Slack](/platform/communication-apps/slack) for the full steps. + + + If Slack is already connected but Hacktron can't read attached archives, + click **Connect** again to grant file access. + + + + + In Hacktron, open **Account**, scroll to **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). + + Slack under Connected Accounts in Hacktron + + + + In Slack, open the channel and send `/invite @Hacktron AI`. You can also + click the channel name, open **Integrations** and click **Add apps**. This + works for public and private channels. + + To send a direct message, find **Hacktron AI** under **Apps** in + the Slack sidebar and send it a message. + + + + 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. + + + +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. + +## 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 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 + + + + Name a connected repository, or attach a `.zip`, `.7z` or `.tar.gz` archive + of the code (up to 2 GB) to your message. + + + To test part of the code, name the folders in the thread, for example "only + the services/payments folder". You can keep the same archive. + + + 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. + + + Hacktron estimates the pentest and asks you to confirm. + + + Hacktron posts an approval card. An organization admin clicks **Start + pentest**. Credits are spent when the pentest starts. + + + When the pentest finishes, Hacktron posts the results in the same thread. + + + +### 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. + + + 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. + + +## Follow what it's doing + +A progress card at the top of the reply shows Hacktron's plan and the steps it takes. + +## 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. +- If Hacktron can't read an attachment, ask an organization admin to reconnect Slack 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 **Account** > **Connected Accounts** in Hacktron, choosing the same workspace, then try again. +- **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. diff --git a/white-box-pentest/quickstart.mdx b/white-box-pentest/quickstart.mdx index f10f1f4..3690b04 100644 --- a/white-box-pentest/quickstart.mdx +++ b/white-box-pentest/quickstart.mdx @@ -199,18 +199,14 @@ For a public target: ## Other ways to start a pentest -You can also set up and start a pentest from Slack, from an AI assistant -connected to the Hacktron MCP server, or from the REST API. Each follows the -same steps as the dashboard: set the scope, estimate the credits, then start. -Only organization admins can start a pentest. +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. - - Mention @Hacktron with a repository or an attached archive. + + Mention @Hacktron AI with a repository or an attached archive. Set up pentests from Claude, Cursor, and other AI assistants. @@ -220,7 +216,7 @@ Only organization admins can start a pentest. icon="code" href="/api-reference/pentests/create-pentest" > - Set up a pentest of code and live sites over the REST API. + Create a draft with repositories or archives, and optional live sites.