# Get Category Distribution Source: https://docs.mindfort.ai/api-reference/analytics/get-category-distribution /openapi.json get /v1/findings/category-distribution # Get Current Metrics Source: https://docs.mindfort.ai/api-reference/analytics/get-current-metrics /openapi.json get /v1/findings/metrics/current # Get Finding Aging Source: https://docs.mindfort.ai/api-reference/analytics/get-finding-aging /openapi.json get /v1/findings/metrics/aging # Get Finding Counts Source: https://docs.mindfort.ai/api-reference/analytics/get-finding-counts /openapi.json get /v1/findings/counts # Get Metrics Timeseries Source: https://docs.mindfort.ai/api-reference/analytics/get-metrics-timeseries /openapi.json get /v1/findings/metrics/timeseries # Get Remediation Metrics Source: https://docs.mindfort.ai/api-reference/analytics/get-remediation-metrics /openapi.json get /v1/findings/metrics/remediation # Get Severity Distribution Source: https://docs.mindfort.ai/api-reference/analytics/get-severity-distribution /openapi.json get /v1/findings/severity-distribution # Get Severity History Source: https://docs.mindfort.ai/api-reference/analytics/get-severity-history /openapi.json get /v1/findings/severity-score-history # Get SLA Metrics Source: https://docs.mindfort.ai/api-reference/analytics/get-sla-metrics /openapi.json get /v1/findings/metrics/sla # Get Target Health Score Source: https://docs.mindfort.ai/api-reference/analytics/get-target-health-score /openapi.json get /v1/targets/{target_id}/health-score # Cancel Assessment Source: https://docs.mindfort.ai/api-reference/assessments/cancel-assessment /openapi.json post /v1/assessments/{assessment_id}/cancel Requests cancellation of a running assessment. The assessment must belong to your organization. # Get Assessment Source: https://docs.mindfort.ai/api-reference/assessments/get-assessment /openapi.json get /v1/assessments/{assessment_id} Retrieve dashboard-aligned assessment progress, including stage_progress, planned testing stages, current statuses, and start/completion timestamps when available. Use stage_progress rather than reconciling expected_testing_stages with stages.state yourself. # List Assessments Source: https://docs.mindfort.ai/api-reference/assessments/list-assessments /openapi.json get /v1/assessments Lists assessments for your organization. Results use cursor pagination and do not include a total count. # Trigger Assessment Source: https://docs.mindfort.ai/api-reference/assessments/trigger-assessment /openapi.json post /v1/assessments/run Requests a new security assessment against the specified target. Accepted assessments run asynchronously; review their status and available results in the MindFort dashboard. # Run MindFort in CI/CD pipelines Source: https://docs.mindfort.ai/api-reference/cicd Run MindFort security assessments from CI/CD, with GitHub Actions examples for kicking off assessments, polling findings, and downloading reports. Integrate MindFort into your CI/CD pipelines to request security assessments on configured push, pull request, or deployment events. This helps make security testing a regular part of your development workflow. ## Prerequisites Before configuring your pipeline, you'll need: 1. **API Key** — Generate one from the [MindFort Dashboard](https://cloud.mindfort.app) under **Settings > API Keys**. 2. **Target ID** — Find this in **Target Inventory** by clicking on the target you want to assess. Store your API key as a secret in your CI/CD platform — never commit it to your repository. ## GitHub Actions Examples ### Trigger an Assessment This example requests a security assessment against your target on pushes or PRs to `main`. Starting a run depends on target readiness, available credits, and whether another assessment is already running. Configure the assessment method with the `MINDFORT_ASSESSMENT_METHOD` variable (`balanced`, `deep`, or `ultra`). These map to the dashboard labels **Balanced**, **Deep**, and **Ultra**. Optionally set `assessment_type` to `black-box` (default) or `white-box`. ```yaml theme={null} name: MindFort Security Assessment on: push: branches: [main] pull_request: branches: [main] jobs: mindfort-assessment: name: Trigger MindFort Assessment runs-on: ubuntu-latest steps: - name: Trigger Assessment id: trigger run: | RESPONSE=$(curl -s -w "\n%{http_code}" \ -X POST "https://api.mindfort.app/v1/assessments/run" \ -H "Authorization: Bearer ${{ secrets.MINDFORT_API_KEY }}" \ -H "Content-Type: application/json" \ -d '{ "target_id": "${{ vars.MINDFORT_TARGET_ID }}", "assessment_method": "${{ vars.MINDFORT_ASSESSMENT_METHOD || 'balanced' }}" }') HTTP_CODE=$(echo "$RESPONSE" | tail -1) BODY=$(echo "$RESPONSE" | sed '$d') echo "status_code=$HTTP_CODE" >> "$GITHUB_OUTPUT" echo "response=$BODY" >> "$GITHUB_OUTPUT" if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then echo "::error::MindFort API returned HTTP $HTTP_CODE: $BODY" exit 1 fi ASSESSMENT_ID=$(echo "$BODY" | jq -r '.assessment_id') echo "assessment_id=$ASSESSMENT_ID" >> "$GITHUB_OUTPUT" echo "Assessment triggered: $ASSESSMENT_ID" - name: Summary if: always() run: | echo "### MindFort Assessment" >> "$GITHUB_STEP_SUMMARY" if [ "${{ steps.trigger.outputs.assessment_id }}" != "" ]; then echo "- **Assessment ID:** \`${{ steps.trigger.outputs.assessment_id }}\`" >> "$GITHUB_STEP_SUMMARY" echo "- **Status:** Triggered" >> "$GITHUB_STEP_SUMMARY" else echo "- **Status:** Failed (HTTP ${{ steps.trigger.outputs.status_code }})" >> "$GITHUB_STEP_SUMMARY" fi ``` | Type | Name | Description | | - | - | - | | Secret | `MINDFORT_API_KEY` | Your MindFort API key | | Variable | `MINDFORT_TARGET_ID` | UUID of the target to assess | | Variable | `MINDFORT_ASSESSMENT_METHOD` | Optional — `balanced` (default), `deep`, or `ultra` | ### List Targets and Findings Use the organization-wide endpoints when you want to discover targets first, then list findings across all targets or within one target. These endpoints use `limit` and `offset` pagination and include a `total` count. ```bash theme={null} curl -G "https://api.mindfort.app/v1/targets" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "limit=25" ``` ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \ --data-urlencode "status=ACTIVE" \ --data-urlencode "exclude_secured=true" \ --data-urlencode "severity=critical" \ --data-urlencode "sort_by=severity" \ --data-urlencode "limit=25" ``` `GET /v1/findings` returns finding summaries with identifiers, target metadata, severity and any override, lifecycle status, timestamps, and retest state. The response includes `total`, `limit`, `offset`, and `next_cursor` pagination metadata. Defaults to `status=ACTIVE`; set `exclude_secured=true` to match the dashboard Open tab (vulnerabilities only). Use `assessment_id` to scope to one assessment run. See [Findings API](/api-reference/findings) for all filters. Use `GET /v1/findings/{finding_id}` to fetch full details, including `description`, `impact`, `evidence`, `approach`, and `remediation_advice`. ### Cancel an Assessment Use the `assessment_id` returned by `POST /v1/assessments/run` or copied from the Assessments page. ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}/cancel" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" ``` The endpoint accepts no request body. ### Poll Assessment Progress Use the assessment detail endpoint when a pipeline needs stage-level progress or a terminal failure reason: ```bash theme={null} curl "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" ``` Use `stage_progress` to track each assessment stage. `NOT_STARTED` means no state has been recorded; `RUNNING` or `ACTIVE` indicates current work. Failed assessments may include a `failure_reason` explaining the problem. If assessment creation fails, inspect the stable public error `code`. For example, `assessment_credits_insufficient` distinguishes billing capacity from authorization, while `assessment_queue_loading` is retryable and includes `Retry-After`. ### Update Finding Status Use status updates to keep triage state in sync from automation. When resolving, you can include `resolve_reason` (`FIX` or `WONT_FIX`) and optional `resolve_context`. ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/status" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"status":"RESOLVED","resolve_reason":"FIX"}' ``` Valid status values are `ACTIVE`, `RESOLVED`, and `ARCHIVED`. ### Generate a Report Create a report for a target, then poll status and download when ready. ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/reports" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "target_id": "'"${MINDFORT_TARGET_ID}"'", "include_secured_findings": true, "include_resolved_findings": false, "report_detail_level": "full" }' ``` ```bash theme={null} curl "https://api.mindfort.app/v1/reports/${MINDFORT_REPORT_ID}" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" ``` ```bash theme={null} curl "https://api.mindfort.app/v1/reports/${MINDFORT_REPORT_ID}/download" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" ``` # Get Coverage Overview Source: https://docs.mindfort.ai/api-reference/coverage/get-coverage-overview /openapi.json get /v1/coverage/overview Get aggregate coverage-check counts, completion progress, team breakdown, and target/team matrix for the organization or one target. Covered, failing, incomplete, in-progress, and not-run checks remain distinct. # List Coverage Checks Source: https://docs.mindfort.ai/api-reference/coverage/list-coverage-checks /openapi.json get /v1/coverage List tested attack paths and scenarios with their status, latest result, last run time, and active related findings. # Check Email MFA Source: https://docs.mindfort.ai/api-reference/credentials/check-email-mfa /openapi.json post /v1/targets/{target_id}/credentials/{credential_id}/check-email-mfa Read the newest credential inbox message and return its one-time MFA code or authorization URL when present. # Check SMS Code Source: https://docs.mindfort.ai/api-reference/credentials/check-sms-code /openapi.json post /v1/targets/{target_id}/credentials/{credential_id}/check-sms Read the latest inbound SMS and return its one-time code when present. # Create Target Credential Source: https://docs.mindfort.ai/api-reference/credentials/create-target-credential /openapi.json post /v1/targets/{target_id}/credentials Store a credential on a target. Email MFA requires pending_email_id; username and password are optional and should be supplied only when the target requests primary credentials. Before adding an api_key credential, the API target must already have non-empty api_auth_instructions; update the target with the validation route, HTTP method, request shape, and successful response first. # Delete Target Credential Source: https://docs.mindfort.ai/api-reference/credentials/delete-target-credential /openapi.json delete /v1/targets/{target_id}/credentials/{credential_id} # Generate Target Email Credential Source: https://docs.mindfort.ai/api-reference/credentials/generate-target-email-credential /openapi.json post /v1/targets/email-credentials Generate a short-lived email address to register for a magic-link or email-MFA credential. # Get Authenticator Code Source: https://docs.mindfort.ai/api-reference/credentials/get-authenticator-code /openapi.json post /v1/targets/{target_id}/credentials/{credential_id}/check-authenticator-2fa Generate the current TOTP code without returning the stored seed. # Get SMS Credential Access Source: https://docs.mindfort.ai/api-reference/credentials/get-sms-credential-access /openapi.json get /v1/targets/sms-credentials/access # List SMS Credential Countries Source: https://docs.mindfort.ai/api-reference/credentials/list-sms-credential-countries /openapi.json get /v1/targets/sms-credentials/available-countries # List Target Credentials Source: https://docs.mindfort.ai/api-reference/credentials/list-target-credentials /openapi.json get /v1/targets/{target_id}/credentials Return credential metadata needed to select and use a configured flow. Stored passwords, API keys, TOTP seeds, inbox IDs, and cached one-time codes are never returned. # Update Target Credential Source: https://docs.mindfort.ai/api-reference/credentials/update-target-credential /openapi.json patch /v1/targets/{target_id}/credentials/{credential_id} # Accept Discovery Suggestion Source: https://docs.mindfort.ai/api-reference/discovery/accept-discovery-suggestion /openapi.json post /v1/discovery/suggestions/{suggestion_id}/accept # Cancel Discovery Run Source: https://docs.mindfort.ai/api-reference/discovery/cancel-discovery-run /openapi.json post /v1/discovery/runs/{run_id}/cancel # Dismiss Discovery Suggestion Source: https://docs.mindfort.ai/api-reference/discovery/dismiss-discovery-suggestion /openapi.json post /v1/discovery/suggestions/{suggestion_id}/dismiss # Get Discovery Status Source: https://docs.mindfort.ai/api-reference/discovery/get-discovery-status /openapi.json get /v1/discovery # List Discovery Suggestions Source: https://docs.mindfort.ai/api-reference/discovery/list-discovery-suggestions /openapi.json get /v1/discovery/suggestions # Start Discovery Run Source: https://docs.mindfort.ai/api-reference/discovery/start-discovery-run /openapi.json post /v1/discovery/runs # Update Discovery Context Source: https://docs.mindfort.ai/api-reference/discovery/update-discovery-context /openapi.json put /v1/discovery/context # Update Discovery Schedule Source: https://docs.mindfort.ai/api-reference/discovery/update-discovery-schedule /openapi.json put /v1/discovery/schedule # Findings API reference Source: https://docs.mindfort.ai/api-reference/findings List, filter, triage, retest, and comment on MindFort findings through the REST API and MCP, and mirror dashboard tabs with status filters. Use `GET /v1/findings` (API key) or the MCP `list_findings` tool (OAuth) to browse findings programmatically. Both surfaces use the same filters and return the same summary fields. ## List findings ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \ --data-urlencode "status=ACTIVE" \ --data-urlencode "exclude_secured=true" \ --data-urlencode "sort_by=severity" \ --data-urlencode "limit=25" ``` ### Query parameters | Parameter | Default | Description | | - | - | - | | `target_id` | — | Filter to one target (UUID from **Target Inventory**) | | `assessment_id` | — | Filter to findings from one assessment run (UUID from **Assessments**) | | `status` | `ACTIVE` | Lifecycle filter: `ACTIVE`, `RESOLVED`, or `ARCHIVED` | | `exclude_secured` | `false` | When `true`, omit informational secured probes (`severity=secured`) | | `severity` | — | Filter by severity: `critical`, `high`, `medium`, `low`, or `secured` (`info` is a deprecated alias for `secured`) | | `sort_by` | `severity` | `severity` (highest score first) or `created_at` | | `order_direction` | `desc` | Sort direction: `asc` or `desc` | | `search` | — | Search finding ID, title, description, endpoint, or impact | | `status_filter` | — | Vulnerability filter: `vulnerable`, `secured`, or `all` | | `active_only` | `false` | When `true`, return only active findings | | `org_wide` | `false` | Compatibility parameter; omit `target_id` and `assessment_id` for organization-wide results | | `assigned_to_me` | `false` | When `true`, return only findings assigned to the current user | | `assigned_to` | — | Filter by assignee user ID | | `unassigned` | `false` | When `true`, return only findings without an assignee | | `finding_type` | — | Only `red-team` findings are available through the public API | | `limit` | `25` | Page size (max `100`) | | `offset` | `0` | Offset for pagination | ### Response Each item in `findings` includes: | Field | Description | | - | - | | `id` | Finding UUID | | `assessment_id` | Assessment UUID when associated with an assessment | | `target_name` | Target name when available | | `finding_type` | Always `red-team` | | `title` | Finding title | | `severity` | `critical`, `high`, `medium`, `low`, or `secured` | | `severity_score` | Numeric score (may be `0` for low-severity or secured items) | | `overridden_severity` | User-selected severity override when one is set | | `status` | `ACTIVE`, `RESOLVED`, or `ARCHIVED` | | `target_id` | Target UUID | | `created_at` | ISO 8601 timestamp | | `updated_at` | ISO 8601 timestamp for the latest visible finding change | | `retest_status` | Current retest execution state when a retest exists | | `retest_started_at` | When the current retest began execution | | `retest_completed_at` | When the current retest completed or failed | | `retest_failure_reason` | Customer-visible reason a retest could not execute | | `retest_in_progress` | `true` while a retest is queued or running | The response also includes `total`, `limit`, `offset`, and `next_cursor` for pagination. Use `offset` until `offset + len(findings) >= total`; `next_cursor` is an opaque pagination marker. ### Match the dashboard The MindFort UI uses tabs and filters that map to API parameters: | Dashboard view | API / MCP equivalent | | - | - | | **Open** (vulnerable only, default) | `status=ACTIVE` and `exclude_secured=true` | | **Open** (include secured probes) | `status=ACTIVE` (omit `exclude_secured` or `exclude_secured=false`) | | **Resolved** | `status=RESOLVED` | | **Archived** | `status=ARCHIVED` | | Findings from one assessment | `assessment_id=` | Without `exclude_secured=true`, list results include informational **secured** probe findings (`severity=secured`) that the dashboard hides on the default Open tab. This can explain why API or MCP counts look higher than the UI. ### Examples **Vulnerabilities for a target (matches default Open tab):** ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \ --data-urlencode "exclude_secured=true" ``` **Findings from a specific assessment:** ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "assessment_id=${MINDFORT_ASSESSMENT_ID}" \ --data-urlencode "exclude_secured=true" ``` **Archived findings:** ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \ --data-urlencode "status=ARCHIVED" ``` ## Get finding details ```bash theme={null} curl "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" ``` Returns full fields including `description`, `impact`, `evidence`, `approach`, `remediation_advice`, `status`, and retest decision context. Use `retest_status` to interpret the current run: * `QUEUED`: accepted but not yet executing * `RUNNING`: execution is in progress * `FAILED`: execution could not complete; inspect `retest_failure_reason` * `COMPLETED`: validation finished and its result was applied to the finding lifecycle ## Update status ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/status" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"status":"RESOLVED","resolve_reason":"FIX"}' ``` Valid values: `ACTIVE`, `RESOLVED`, `ARCHIVED`. When `status` is `RESOLVED`, you may include `resolve_reason` (`FIX` or `WONT_FIX`) and optional `resolve_context` (max 2000 characters). Bulk updates are available at `POST /v1/findings/status` with up to 50 `finding_ids`. ## Override severity ```bash theme={null} curl -X PATCH "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/severity" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"severity":"high"}' ``` Accepted values: `critical`, `high`, `medium`, `low`, `secured`. Pass `null` to clear an override. `info` is accepted only as a deprecated alias for `secured`. ## Retest a finding ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/retest" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" ``` Starts an asynchronous retest for an `ACTIVE`, `RESOLVED`, or `ARCHIVED` finding. The request fails if another retest is already queued or running. Poll `GET /v1/findings/{finding_id}` after the request is accepted. When the retest completes, MindFort applies the validation result: * A retest result indicating the issue is fixed under the tested conditions sets the finding to `RESOLVED`. * A retest result indicating the issue remains reproducible sets the finding to `ACTIVE`. * An execution failure leaves the security outcome unchanged and populates `retest_failure_reason`. Retest `RUNNING` and `FAILED` transitions update the finding's `updated_at`, so change-based consumers can observe them. ## Comments ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "limit=25" ``` ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"content":"Patched in PR #482 — ready for retest."}' ``` Edit with `PATCH /v1/findings/{finding_id}/comments/{comment_id}` and delete with `DELETE /v1/findings/{finding_id}/comments/{comment_id}`. ## Patch summaries ```bash theme={null} curl -G "https://api.mindfort.app/v1/findings/patches" \ -H "Authorization: Bearer ${MINDFORT_API_KEY}" \ --data-urlencode "limit=50" ``` Returns findings that have patch activity, including `pr_url`, `patch_status`, and `patch_state`. Use `assigned_to_me=true` to restrict to the current user's findings or `search` to match finding ID, title, description, endpoint, or impact. Authorized organizations receive the stored GitHub pull-request URL, including private repository URLs. Patch activity is independent of finding lifecycle status. ## Analytics Finding analytics endpoints accept an optional `target_id`. Omit it for organization-wide metrics. `GET /v1/findings/severity-score-history` accepts `granularity` (`day`, `week`, or `month`), and remediation metrics additionally accept optional inclusive `from` and `to` dates. | Endpoint | Description | | - | - | | `GET /v1/findings/counts` | Lifecycle, exposure, and severity counts | | `GET /v1/findings/severity-distribution` | Severity distribution | | `GET /v1/findings/category-distribution` | OWASP and vulnerability tag distribution | | `GET /v1/findings/severity-score-history` | Severity score history | | `GET /v1/findings/metrics/current` | Current security metrics | | `GET /v1/findings/metrics/timeseries` | Timeseries metrics (`from`, `to`, optional `granularity`) | | `GET /v1/findings/metrics/remediation` | Remediation metrics (MTTR) | | `GET /v1/findings/metrics/sla` | SLA breach metrics | | `GET /v1/findings/metrics/aging` | Finding age buckets | Target health score is available at `GET /v1/targets/{target_id}/health-score`. ## MCP The [MCP guide](/guides/mcp) exposes the same semantic filters on the `list_findings` tool. Pass `target_id`, `assessment_id`, `status`, `exclude_secured`, `severity`, `sort_by`, `order_direction`, `search`, or assignment filters; MCP collection tools use an opaque `cursor` rather than a raw offset. After a server update, you do **not** need to reinstall MCP — keep the same `https://api.mindfort.app/mcp` URL and restart your agent or start a new chat so it picks up the latest tool schema. ## Recover a retest credential When `retest_failure_code` identifies an authentication failure or an unavailable credential, retry with a replacement credential from the same target. The public retest request accepts `target_credential_id` for a replacement primary credential. To review both accounts for a dual-credential finding, use the dashboard. Replacement is allowed only after a qualifying credential failure. It changes future retest credentials, not the credentials recorded for the original finding. Inspect `retest_failure_reason` for the customer-visible explanation. See [Retesting findings](/guides/retesting). ## Record a false positive When updating a finding's lifecycle status, a false-positive decision uses `status: "ARCHIVED"`, `resolve_reason: "FALSE_POSITIVE"`, and a nonempty `resolve_context` explaining the decision. `FIX` and `WONT_FIX` are resolution reasons for `RESOLVED` findings. See the status endpoint schema for the complete request contract. # Add Finding Comment Source: https://docs.mindfort.ai/api-reference/findings/add-finding-comment /openapi.json post /v1/findings/{finding_id}/comments # Delete Finding Comment Source: https://docs.mindfort.ai/api-reference/findings/delete-finding-comment /openapi.json delete /v1/findings/{finding_id}/comments/{comment_id} # Edit Finding Comment Source: https://docs.mindfort.ai/api-reference/findings/edit-finding-comment /openapi.json patch /v1/findings/{finding_id}/comments/{comment_id} # Get Finding Source: https://docs.mindfort.ai/api-reference/findings/get-finding /openapi.json get /v1/findings/{finding_id} Retrieve full details for a single security finding, including its description, impact, evidence, reproduction approach, remediation advice, current status, and retest decision context such as why execution failed. # Get Patch Count Source: https://docs.mindfort.ai/api-reference/findings/get-patch-count /openapi.json get /v1/findings/patch-count Return the number of findings with a generated remediation patch. # List Finding Comments Source: https://docs.mindfort.ai/api-reference/findings/list-finding-comments /openapi.json get /v1/findings/{finding_id}/comments # List Finding Patches Source: https://docs.mindfort.ai/api-reference/findings/list-finding-patches /openapi.json get /v1/findings/patches # List Findings Source: https://docs.mindfort.ai/api-reference/findings/list-findings /openapi.json get /v1/findings Lists security findings across your organization, optionally filtered by target and lifecycle status. Defaults to ACTIVE findings. Results include the current retest status, timestamps, and customer-visible failure reason when a retest could not execute. Results use offset pagination and include a total count. # Retest Finding Source: https://docs.mindfort.ai/api-reference/findings/retest-finding /openapi.json post /v1/findings/{finding_id}/retest # Update Finding Severity Source: https://docs.mindfort.ai/api-reference/findings/update-finding-severity /openapi.json patch /v1/findings/{finding_id}/severity # Update Finding Status Source: https://docs.mindfort.ai/api-reference/findings/update-finding-status /openapi.json post /v1/findings/{finding_id}/status Update a finding to ACTIVE, RESOLVED, or ARCHIVED to track remediation progress across your organization. # Update Finding Statuses Source: https://docs.mindfort.ai/api-reference/findings/update-finding-statuses /openapi.json post /v1/findings/status # MindFort API introduction Source: https://docs.mindfort.ai/api-reference/introduction Authenticate to the MindFort API and manage authorized targets, credentials, coverage checks, assessments, findings, analytics, and reports. ## Base URL All API requests are made to: ```text theme={null} https://api.mindfort.app ``` ## Authentication The MindFort API uses **Bearer token** authentication. Include your MindFort API key in the `Authorization` header of every request: ```bash theme={null} Authorization: Bearer ``` You can generate API keys from the [MindFort Dashboard](https://cloud.mindfort.app) under **Settings > API Keys**. ## Rate Limits * **Per-client limit:** 60 requests per minute * **Global limit:** 100 requests per minute When rate-limited, responses include a `Retry-After: 60` header. The API returns HTTP `429` with an error message. ## API Surface The public REST API exposes the approved organization-scoped product surface: * list, get, create, update, and confirmed deletion of targets * create, rotate, inspect metadata for, and delete test credentials * read coverage checks and aggregate coverage * discover candidate targets and manage discovery suggestions when enabled * run, list, inspect, and cancel assessments * list and get findings; update lifecycle status; override severity; retest * manage finding comments and inspect patch summaries and counts * read finding analytics, security metrics, aging, remediation, SLA, and health scores * create, list, poll, and download reports Use the endpoint reference for request and response schemas, query parameters, and examples. The API does not expose target-verification operations, billing administration, API-key administration, organization membership, or role administration. Complete those workflows in the [MindFort Dashboard](https://cloud.mindfort.app). ## REST and MCP REST and MCP share organization-scoping rules and core resource contracts, but their available operations, authentication, and pagination differ. Assessment schedule management is available through MCP; it has no public REST routes. | Surface | Authentication | Pagination | Best for | | - | - | - | - | | **REST API** | MindFort API key | Cursor or `limit`/`offset`, depending on the endpoint | CI/CD, services, scripts, and deterministic integrations | | **MCP Server** | Browser-based OAuth | Opaque `cursor` values on list tools | Interactive AI agents using MindFort context | The MCP catalog is explicit and may omit feature-gated tools or schema variants that are unavailable to the selected organization. See the [MCP guide](/guides/mcp). ## Target and Credential Rules Targets are scoped to the authenticated organization: * `web_app` and `api` targets require an HTTP(S) `web_domain`. * `network` targets require an `ip_address` and the `network-targets` organization feature. * Targets created through REST or MCP begin unverified. Complete domain ownership or network verification in the dashboard before starting active testing. * Target URLs containing embedded `user:password@host` credentials are rejected. Credential list and detail reads return metadata only, omitting passwords, API-key values, and TOTP seeds. Dedicated code-check endpoints can return temporary authentication codes or login URLs; email provisioning returns a pending inbox ID for credential creation. An `api_key` credential is valid only for an `api` target. Before adding one, set nonblank target-level `api_auth_instructions` that describe the validation route, method, request shape, key placement, and expected successful response. ## Coverage Coverage shows security scenarios tested across assessments. Use `GET /v1/coverage` to list checks and `GET /v1/coverage/overview` for aggregate counts, optionally filtered by `target_id`. The current states are `covered`, `failing`, `incomplete`, `in_progress`, and `not_run`. Responses include scenario details, run summaries, and related findings. Coverage is read-only; assessments maintain the checks and run history. See [Coverage](/guides/coverage). ## Discovery When Discovery is enabled, use `/v1/discovery` to inspect its status, configure context and schedules, start runs, and accept or dismiss candidate targets. See [Target discovery](/guides/discovery) for the operation list. ## Pagination REST list endpoints use two pagination styles: * `GET /v1/assessments` uses cursor pagination. Pass the returned `pagination.next_cursor` value as the next request's `cursor` parameter until no next cursor is returned. * Target, credential, coverage, finding, comment, patch, and report collections use the pagination fields documented on their endpoint schemas. Offset-based responses include a `total`; cursor-based responses return `next_cursor` when another page is available. Do not construct or modify cursor values. Pass each cursor back unchanged with the same filters. ## Error Format Errors follow a consistent public JSON structure: ```json theme={null} { "error": "Human-readable error message", "code": "stable_error_code", "request_id": "abc123..." } ``` The `code` field is present for recognized actionable failures. Responses may also include safe field validation details. Include the `request_id` when contacting support. Examples of stable error codes include: * `target_not_verified` * `api_auth_instructions_required` * `assessment_already_running` * `assessment_credits_insufficient` * `assessment_queue_loading` * `retest_already_running` Retryable responses may include `Retry-After`. If you receive HTTP `429 Too Many Requests`, wait for the interval specified by that header before retrying and reduce request frequency. Coordinate polling across integrations that share your organization. ## Component IDs Several API endpoints require UUIDs for targets, findings, assessments, reports, and other resources. Below is where to find each ID in the MindFort dashboard. ### Targets Navigate to **Target Inventory** and click on a target. The **Target ID** is displayed on the target's detail page. ### Findings Use `GET /v1/findings` or open a finding in the dashboard. The **Finding ID** identifies a specific vulnerability for detail, comment, status, severity, and retest requests. Filter list results with `status`, `assessment_id`, `exclude_secured`, `target_id`, and `severity`. See [Findings API](/api-reference/findings) for parameter details and dashboard mapping. ### Assessments Open **Assessments**, select a run, and copy the **Assessment ID** from the URL or detail view. Use it as `assessment_id` when listing findings for that run only. Use `stage_progress` in assessment detail to track each stage. `NOT_STARTED` means the stage has no recorded state; `RUNNING` or `ACTIVE` indicates current work; other values are terminal outcomes. Failed runs may include a `failure_reason` explaining the problem. ### Credentials List credentials under a target to obtain credential IDs and safe metadata. Use credential IDs when running authenticated assessments or rotating/deleting a credential. Credential list responses contain metadata only. ### Reports Create a report with `POST /v1/reports`, then poll `GET /v1/reports/{report_id}` until it is ready and call `GET /v1/reports/{report_id}/download` for a short-lived download URL. ## Content Type All endpoints accept and return `application/json`. Requests with a JSON body must include: ```http theme={null} Content-Type: application/json ``` ## Plan and role access An API key does not bypass feature, billing, or permission checks. Reporting and retesting require an upgraded plan. Discovery and network-target capabilities also require the corresponding organization features. # Create Report Source: https://docs.mindfort.ai/api-reference/reports/create-report /openapi.json post /v1/reports # Download Report Source: https://docs.mindfort.ai/api-reference/reports/download-report /openapi.json get /v1/reports/{report_id}/download # Get Report Source: https://docs.mindfort.ai/api-reference/reports/get-report /openapi.json get /v1/reports/{report_id} # List Reports Source: https://docs.mindfort.ai/api-reference/reports/list-reports /openapi.json get /v1/reports # Create Target Source: https://docs.mindfort.ai/api-reference/targets/create-target /openapi.json post /v1/targets # Delete Target Source: https://docs.mindfort.ai/api-reference/targets/delete-target /openapi.json delete /v1/targets/{target_id} Permanently delete a target after confirming its exact name. Deletion is rejected while an assessment is queued or running. # Get Target Source: https://docs.mindfort.ai/api-reference/targets/get-target /openapi.json get /v1/targets/{target_id} # List Targets Source: https://docs.mindfort.ai/api-reference/targets/list-targets /openapi.json get /v1/targets List all targets in your organization using limit and offset pagination to discover which applications and assets are available for testing. # Update Target Source: https://docs.mindfort.ai/api-reference/targets/update-target /openapi.json patch /v1/targets/{target_id} # Analytics Source: https://docs.mindfort.ai/guides/analytics Review organization-wide security metrics, vulnerability trends, and finding severity over time, or focus the view on a single target in MindFort. ## Overview Open **Analytics** to review security trends across your organization. Use the target selector to switch between the organization-wide view and a single target. ## Available Metrics Analytics can show: * findings over time * finding categories * vulnerability tags * remediation speed * age of open findings Use these metrics to identify recurring vulnerability classes, prioritize aging risk, and track remediation progress. ## Recommended Process 1. Start with the organization-wide view to identify the largest trends. 2. Select a target to investigate a change or outlier. 3. Open **Findings** to review the individual issues behind a metric. 4. Revisit Analytics after remediation to review resolution trends. Use Analytics for trends over time. Use [Coverage](/guides/coverage) to review current scenarios, run states, and linked findings. ## Interpret the metrics **Time to Fix** shows the average time from discovery to recorded resolution for resolved, non-informational red-team findings. Deleted findings and findings from assessments without results are excluded. Review it alongside the number of resolved findings, since a small sample can move the average substantially. **Open Findings Aging** describes unresolved findings. An empty remediation view means no remediation data is available for the selected scope; it does not establish that there are no open findings. Use the same target scope when comparing analytics with a finding list. Analytics is not available to members whose only role is auditor. # Assessments Source: https://docs.mindfort.ai/guides/assessments Learn how to start, schedule, monitor, and cancel autonomous penetration-test assessments, and choose the Balanced, Deep, or Ultra method. Assessments are designed for broad, autonomous penetration testing of a configured target. Coverage depends on the target's scope, available access, and the scenarios investigated during the run. For directed security work, see [Agents](/guides/tasks). ## Start an Assessment 1. Click **New Assessment**. 2. Select target. 3. Choose **Black-Box** or **White-Box** when available. 4. Optionally select stored credentials. 5. Configure scheduling. 6. Select assessment method. 7. Start assessment. Choose **Black-Box** for external testing. Choose **White-Box** to include source-code analysis; [link a repository to the target](/guides/targets#link-source-repositories) before selecting it. Network targets support Black-Box testing only. ## Assessment Methods When creating an assessment, choose a method based on your needs: * **Balanced** — Designed for frequent runs. Uses 200 credits, with an estimated runtime of 6 hours. * **Deep** — More time for investigation. Uses 400 credits, with an estimated runtime of 8 hours. * **Ultra** — Extended testing for deeper investigation. Uses 800 credits, with an estimated runtime of 12 hours. The assessment form shows the current credit cost and estimated duration before you start. Actual run times vary with the target and execution conditions. The public API uses the method values `balanced`, `deep`, and `ultra`, which map to the dashboard labels **Balanced**, **Deep**, and **Ultra**. ## Assessment Use Cases Use assessments to investigate potential vulnerabilities and review any findings with supporting evidence. | Use Case | When to Run | | - | - | | **Initial target assessment** | After onboarding a new web app or API target. | | **Authenticated coverage** | After adding stored credentials and login instructions. | | **Access-control testing** | When you need to test user, role, tenant, or account boundaries. | | **Dual-account testing** | When two stored credentials are available and you want to test IDOR, role bypass, or cross-user access. | | **Release validation** | Before or after a major application release. | | **Recurring security coverage** | On a daily, weekly, or monthly schedule for high-value targets. | | **Post-remediation validation** | After engineers fix critical or high findings and you want a fresh autonomous pass. | Assessments are the broad discovery workflow. Use [Agents](/guides/tasks) for narrower follow-up investigations, and use [Patching](/guides/patching) or [MCP](/guides/mcp) when you are ready to remediate. ## Monitor Progress In **Assessments**, track: * active and queued runs * scheduled runs * historical runs Open an assessment to review progress and evidence entries as they populate. You can also list assessments from the public API. It supports cursor pagination and filters for target, assessment type, method, and status: ```bash theme={null} curl "https://api.mindfort.app/v1/assessments?assessment_type=white-box&status=active&limit=25" \ -H "Authorization: Bearer $MINDFORT_API_KEY" ``` Supported assessment type filters are `black-box` and `white-box`. White-box assessments include code assessment; black-box assessments do not. Supported status filters are `active`, `completed`, `failed`, and `canceled`. ## Scheduling You can create recurring schedules directly from the New Assessment modal. Frequency options include: * one-time * daily * weekly * bi-weekly * monthly For a one-time run, start immediately or schedule it for later. Set the target, optional credentials, frequency, date/time, and timezone when creating a schedule. In **Scheduled Assessments**, you can review and delete existing schedules. ## Manage schedules through MCP MCP supports listing, inspecting, creating, updating, pausing, resuming, deleting, and triggering assessment schedules. Start with `list_assessment_schedules` and use the returned schedule ID for subsequent actions. * Pausing stops future scheduled runs without canceling assessments already created. * Resuming uses the saved cadence and configuration. * Triggering an enabled schedule requests a run without changing its cadence. * Deleting a schedule stops future runs; existing assessments remain available. Multiple schedules can share a target when their occurrences are at least five minutes apart. Assessments for the same target run one at a time; additional runs wait in the queue and start automatically. See the [MCP tool catalog](/guides/mcp#complete-tool-catalog). ## Dual Credential Mode For authenticated assessments, enable **Dual credential mode** when you want MindFort to test access-control boundaries between two stored accounts. Dual credential mode uses: * a primary credential for the first account * a secondary credential for the alternate account Use it to test issues such as IDOR, role bypass, and cross-user access. Add at least two stored credentials to the target before enabling dual credential mode. ## Cancel a Running Assessment 1. Open **Assessments**. 2. Find the active run. 3. Click cancel and confirm. You can also cancel a running assessment from the public API: ```bash theme={null} curl -X POST "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}/cancel" \ -H "Authorization: Bearer $MINDFORT_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Evidence Open a completed assessment to view the **Assessment Log**. The log shows timestamped evidence rows with the endpoint and notes captured during the run. Assessment log entries older than 30 days are automatically cleared. ## Review coverage after a run Open [Coverage](/guides/coverage) to inspect tested scenarios, incomplete work, and linked findings. Review [Analytics](/guides/analytics) for trends across runs. Scheduling is available on all plans; a scheduled run still needs a ready target and sufficient credits or applicable usage-based billing. # Authentication & Credentials Source: https://docs.mindfort.ai/guides/authentication-credentials Learn how to configure password, magic link, 2FA, email, SMS, and API credentials in MindFort so agents can run authenticated security tests. ## Why Add Credentials Credentials help assessments access authenticated areas that are not visible to public crawling. Credentials and login instructions are used together: * credentials provide what to enter * login instructions provide where and how agents should log in ## Credential Types MindFort supports multiple credential types. Each targets a different authentication flow your application may use. | Type | Auth Flow | | - | - | | **Application Login** | Username & password | | **Authenticator 2FA** | Username, password & TOTP code | | **Email MFA** | Username, password & email verification code | | **Magic Link** | Passwordless email sign-in link | | **SMS MFA** | Username, password & SMS code | | **SMS Login** | Phone number & SMS code only | | **API Key** | Bearer, header, query parameter, or JSON body credential for API targets | ### Application Login Standard username and password authentication. | Field | Required | | - | - | | Credential Name | Yes | | Username | Yes | | Password | Yes | | Role | Yes (default: user) | | Description | No | **Setup:** 1. Open **Target Inventory** and select a target. 2. Click **Add Credential** and choose **App Login**. 3. Enter the username and password for the test account. 4. Select the appropriate role and save. ### Authenticator 2FA Username and password authentication with a TOTP-based second factor. MindFort generates time-based codes automatically during assessments using the secret you provide. | Field | Required | | - | - | | Credential Name | Yes | | Username | Yes | | Password | Yes | | TOTP Secret | Yes | | Role | Yes (default: user) | | Description | No | The TOTP secret is the base32-encoded string shown when you set up an authenticator app (e.g. `JBSWY3DPEHPK3PXP`). You can usually find this during the authenticator setup flow where a QR code is displayed — look for a "Can't scan?" or "Manual entry" option to reveal the text secret. **Setup:** 1. Open **Target Inventory** and select a target. 2. Click **Add Credential** and choose **2FA**. 3. Enter the username, password, and the base32 TOTP secret. 4. Select the appropriate role and save. ### SMS MFA Username and password authentication where the second factor is an SMS verification code. MindFort provisions a dedicated phone number and reads incoming codes during assessments. | Field | Required | | - | - | | Credential Name | Yes | | Username | Yes | | Password | Yes | | Country Code | Yes | | Role | Yes (default: user) | | Description | No | A phone number is provisioned automatically when the credential is created. You will see it in the credentials table once provisioning completes. Register this number as the MFA phone number on the target account. **Setup:** 1. Open **Target Inventory** and select a target. 2. Click **Add Credential** and choose **SMS MFA**. 3. Enter the username and password for the test account. 4. Select the country for the provisioned phone number. 5. Save the credential — a phone number will be provisioned. 6. Copy the provisioned phone number from the credentials table and register it as the MFA number on your target application's account settings. 7. *(Optional)* If the target application sends a verification code to confirm the phone number during registration, click the message icon in the credentials table Actions column and press **Check for Code** to retrieve it. Enter the code in the target application to complete registration. ### SMS Login Phone-number-only authentication where a one-time code is sent via SMS instead of using a password. MindFort provisions a dedicated phone number and reads incoming codes during assessments. | Field | Required | | - | - | | Credential Name | Yes | | Country Code | Yes | | Role | Yes (default: user) | | Description | No | No username or password is needed. A phone number is provisioned automatically. **Setup:** 1. Open **Target Inventory** and select a target. 2. Click **Add Credential** and choose **SMS Login**. 3. Select the country for the provisioned phone number. 4. Save the credential — a phone number will be provisioned. 5. Copy the provisioned phone number from the credentials table and register it as a user on your target application. 6. *(Optional)* If the target application sends a verification code during account creation, click the message icon in the credentials table Actions column and press **Check for Code** to retrieve it. Enter the code in the target application to complete registration. ### Email MFA Username and password authentication where the second factor is sent to a dedicated email inbox. MindFort generates the email address during credential setup and uses it during assessments. | Field | Required | | - | - | | Credential Name | Yes | | Username | Yes | | Password | Yes | | Generated Email | Yes | | Role | Yes (default: user) | | Description | No | **Setup:** 1. Open **Target Inventory** and select a target. 2. Click **Add Credential** and choose **Email MFA**. 3. Enter the username and password for the test account. 4. Generate the email address in the credential form. 5. Register that email address as the MFA email on the target account. 6. Save the credential. ### Magic Link Passwordless authentication where the application sends a sign-in link to a generated email address. No username or password is required. **Setup:** 1. Open **Target Inventory** and select a Web Application target. 2. Click **Add Credential** and choose **Magic Link**. 3. Generate the email address. 4. Register that address with the target application. 5. Save the credential. 6. Add login instructions that explain where to request the link and which page confirms a successful sign-in. ### API Key API key credentials are available for API targets. Use them when the target authenticates requests with a bearer token, custom header, query parameter, JSON body field, or additional required fields. API targets require content in **API Structure** before API key credentials can be added. Describe the validation route, request method, request shape, and success criteria there. | Field | Required | | - | - | | Credential Name | Yes | | API Key or Token | Yes | | Placement | Yes | | Additional Fields | No | | Role | Yes (default: user) | | Description | No | **Setup:** 1. Open **Target Inventory** and select an API target. 2. Click **Add Credential** and choose **API Key**. 3. Enter the key or token. 4. Select where MindFort should place the credential: header, bearer token, query parameter, or JSON body field. 5. Add any extra static fields the API requires. 6. Save the credential. ### SSO Redirect Flows For applications that authenticate through an identity provider redirect flow, create a dedicated test account and document the full redirect flow in login instructions. Include: * the application login URL * the identity provider option to choose * any tenant, workspace, or organization selector * the expected post-login URL * whether MFA is required for the test account If the SSO flow requires an email, phone, or authenticator second factor, configure the matching credential type and include the SSO steps in login instructions. ## Credential setup by authentication flow | Flow | Recommended Setup | | - | - | | Username and password | Application Login credential | | Authenticator app MFA | Authenticator 2FA credential with TOTP secret | | Email verification code | Email MFA credential with generated email address | | Passwordless email link | Magic Link credential with generated email address | | SMS second factor | SMS MFA credential with provisioned phone number | | SMS-only login | SMS Login credential | | API key or token | API Key credential on an API target | | SSO redirect flow | Stored test credential plus explicit login instructions | | Phone-number login | SMS Login credential plus explicit login instructions | ## Credential Guidelines * Use dedicated test accounts — avoid personal or production admin accounts. * Keep account access scoped to what you want tested. * Prefer least-privilege roles that still exercise the features you want assessed. * Create separate credentials for materially different roles, such as user and admin. * Create at least two distinct stored credentials when you want to use assessment dual credential mode for access-control boundary testing. * Rotate credentials regularly. * For SMS credential types, contact support if the option is not available for your organization. ## Related Setup After adding credentials, add clear login instructions to help agents navigate your target's sign-in flow: [Writing Login Instructions](/guides/login-instructions) ## Credential-specific API instructions Use **Additional Auth Instructions** on an API credential for steps that apply to that account, such as exchanging a key for a session token or selecting a tenant. MindFort combines these instructions with the target's **API Structure** when signing in and renewing access during testing. The REST API field is `additional_auth_instructions`. It accepts up to 10,000 characters of plain text. Omit it during an update to preserve the existing value; whitespace-only input clears it. HTML tags and unsupported control characters are rejected. MCP credential tools do not currently expose this field; use the dashboard or REST API to set it. ## Verify credentials 1. Open the target in **Target Inventory**. 2. Find the credential in **Stored Credentials**. 3. Select **Verify** and wait for the result. 4. If verification fails, inspect the reported reason, update the credential or instructions, and verify again. If a finding retest fails because an account is invalid or unavailable, you can choose replacement credentials from the finding details. See [retest credential recovery](/guides/retesting#recover-from-an-authentication-failure). Verification checks whether MindFort can authenticate with the current configuration. A successful check reflects that attempt; it does not establish security coverage for the target. Keep credentials and instructions current before starting assessments or [retests](/guides/retesting). # Coverage Source: https://docs.mindfort.ai/guides/coverage Review the security scenarios MindFort has tested, their latest run states, and linked findings across your targets. ## Overview Open **Coverage** to review security scenarios across your targets. Each check describes an attack path or a set of related scenarios. MindFort maintains these checks as it learns about the target during assessments. Search by target name or address, filter by target type, and sort the target list to prioritize gaps or failing checks. Select a target to inspect individual checks, their latest run summaries, and related findings. ## Understand check states | State | Meaning | | - | - | | **Covered** | The latest run completed and the check has no active linked finding. | | **Failing** | The check is linked to a currently active finding. | | **Incomplete** | The latest run could not finish. | | **In progress** | MindFort is testing the check. | | **Not run** | The check has not been tested yet. | A completed run records that its assigned scenarios were investigated. It does not guarantee that the target has no vulnerabilities. Active linked findings determine whether a check is failing; resolving a finding can change that status. Checks persist across assessments. Run records preserve the scenarios tested at that time, even when MindFort later revises the check. ## Review gaps 1. Open a target with failing, incomplete, or untested checks. 2. Read the check's scenarios and latest summary. 3. Review linked findings and their remediation guidance. 4. Correct any target setup or access issues identified in the summary. 5. Run another [assessment](/guides/assessments) when you need updated coverage. Coverage is read-only. You cannot create, edit, delete, or rerun individual checks from this page. ## API and MCP Use `GET /v1/coverage` to list checks and `GET /v1/coverage/overview` for aggregate counts. MCP provides `list_coverage_checks` and `get_coverage_overview`. Both support organization-wide or target-specific views. Use [Analytics](/guides/analytics) for trends over time and Coverage for the current state of tested scenarios. # Overview Dashboard Source: https://docs.mindfort.ai/guides/dashboard Learn how to use the MindFort Overview dashboard to monitor security posture, track active assessments, and decide which targets to triage next. ## What You See The dashboard gives you a top-level view of: * overall health score and recent trend * target health, including active assessment indicators * unresolved findings over time * recommended next actions ## How to Use It 1. Open **Overview** from the sidebar. 2. Review the overall health score and change from the previous week. 3. Select a target row to review its findings. 4. Use **Quick Actions** to verify a target, start or rerun an assessment, launch an agent, or view your highest-severity findings. ## Best Practice Use the dashboard as a daily status check, then move to **Assessments**, **Findings**, or **Coverage** for detailed action. # Target discovery Source: https://docs.mindfort.ai/guides/discovery Review candidate targets in Target Inventory and manage discovery context, schedules, and suggestions through the dashboard, API, or MCP. ## Overview Discovery proposes candidate targets for your organization. Review suggestions before accepting them into your target inventory. Discovery is available only when enabled for your organization. The public API and MCP support the following workflow: 1. Read the current discovery status, context, and schedule. 2. Update the context note with information that helps identify your organization's assets. 3. Start a discovery run or configure a recurring schedule. 4. List pending suggestions. 5. Accept relevant suggestions or dismiss those you do not want to add. Accepting a suggestion creates a target through the normal target workflow. Check its verification state and complete any required ownership verification before starting an assessment. ## Dashboard When Discovery is enabled, open **Target Inventory** to find its Discovery panel. The panel provides: * **Add background**, **Edit background**, or **View background** for organization-specific information that guides discovery. * **Schedule** for the cadence, local time, and time zone. * **Run now** and **Stop** controls, with current run status. * **Accept** and **Dismiss** actions on candidate targets. Review a suggestion before accepting it. Acceptance adds a target; it does not demonstrate that the target has been assessed or that ownership verification is complete. Owners and admins manage discovery from the dashboard. Other members can review available background and suggestions. ## API operations | Action | Endpoint | | - | - | | Read status | `GET /v1/discovery` | | Set context | `PUT /v1/discovery/context` | | Set schedule | `PUT /v1/discovery/schedule` | | Start a run | `POST /v1/discovery/runs` | | Cancel a run | `POST /v1/discovery/runs/{run_id}/cancel` | | List suggestions | `GET /v1/discovery/suggestions` | | Accept a suggestion | `POST /v1/discovery/suggestions/{suggestion_id}/accept` | | Dismiss a suggestion | `POST /v1/discovery/suggestions/{suggestion_id}/dismiss` | Schedules support daily or weekly runs, a local time, and an IANA time zone such as `America/Los_Angeles`. Weekly schedules require `day_of_week`, where `0` is Monday and `6` is Sunday. Daily schedules omit that field or set it to `null`. Suggestions have a lifecycle status of `pending`, `accepted`, `dismissed`, or `superseded`. Use the endpoint reference for request fields and pagination. ## MCP Begin with `get_current_context` to check whether Discovery is enabled. Use `get_discovery_status`, `update_discovery_context`, and `update_discovery_schedule` to inspect and configure it. Run and review discovery with `start_discovery_run`, `list_discovery_suggestions`, `accept_discovery_suggestion`, and `dismiss_discovery_suggestion`. # Dual Credentials Source: https://docs.mindfort.ai/guides/dual-credentials Learn how to run dual-credential assessments with two stored accounts to test IDOR, broken access control, and privilege boundaries between users. ## What Dual Credentials Are For Dual credential mode lets an authenticated assessment use two stored accounts for the same target. This helps MindFort test whether one authenticated user can access data or actions that should belong to another user. Use dual credentials to help investigate: * IDOR and broken object-level authorization * role bypass and privilege boundary issues * cross-user data access * tenant or account isolation problems ## Before You Start Add at least two stored credentials to the target. The credentials should represent the access boundary you want tested, such as two standard users, a standard user and an admin, or users from different accounts or tenants. For credential setup details, see [Authentication & Credentials](/guides/authentication-credentials). ## Run With Dual Credentials Start a new assessment and select the target you want to test. In **Credentials**, turn on **Dual credential mode**. This option is available after the target has at least two stored credentials. Choose the primary credential and the secondary credential. MindFort can use both accounts to compare what each user can access. Run the assessment immediately or configure a recurring schedule. Scheduled assessments keep the selected primary and secondary credentials. ## Choosing Credential Pairs Choose accounts with clear access boundaries to help investigate authorization issues: * Two regular users with separate data sets * A low-privilege user and a higher-privilege user * Users from different organizations, workspaces, or tenants * Accounts with intentionally different feature access Avoid using personal or production admin accounts. Dedicated test accounts help clarify access boundaries and reduce risk. ## Retest a two-account finding Retesting uses both saved accounts when the finding requires them. Keep both credentials valid after deploying a fix. If authentication fails or an account is no longer available, select **Choose another credential** in the finding details. Review the primary and secondary selections, choose two different accounts for the same target, and select **Retest**. You can replace either account, and your choices also apply to future retests of that finding. See [Retesting](/guides/retesting#recover-from-an-authentication-failure). ## Related Guides * [Targets](/guides/targets) * [Authentication & Credentials](/guides/authentication-credentials) * [Assessments](/guides/assessments) # Findings and triage Source: https://docs.mindfort.ai/guides/findings Browse targets, drill into vulnerability findings, assign owners, add comments, and manage the full finding lifecycle in the MindFort dashboard. ## Browse Findings Open **Findings** to view findings across your organization. Use the target selector to show all targets or focus on one target. Search findings, filter by severity or assignee, and sort the results to focus your triage. ## Drill Into a Target Use the target selector to focus on one target. Then: * switch between **Open**, **Resolved**, and **Archived** * include secured findings in the Open view when needed * filter, search, sort, and page through results ## Finding Actions Open a finding to: * review full details, evidence, proof-of-concept detail, and AI-generated summaries * assign or unassign an owner * add comments * resolve or reopen the finding * create a linked issue in Linear or Jira (if connected) * request a patch (if available) * archive, unarchive, or delete when appropriate * start retest actions when available ## Pin findings for follow-up Select **Pin finding** on a finding to keep it near the top of your results. Select **Unpin finding** to remove it. Pins still respect your current filters. You can pin up to 100 findings. Pins are personal to your account and organization in the current browser; they are not shared with teammates or synchronized across browsers. Members whose only role is auditor cannot pin findings. ## Recover a retest with failed credentials If a retest reports an authentication failure or an unavailable credential, select **Choose another credential** in the finding details. Choose a valid credential from the same target, review both accounts for a dual-account finding, and select **Retest**. See [credential recovery](/guides/retesting#recover-from-an-authentication-failure) for the full steps. ## Finding Artifacts Finding details provide context to help security and engineering teams investigate, prioritize, and address reported issues. Depending on the finding type, details can include: * severity * CVSS v3.1 score * OWASP category and vulnerability tags * exploitability assessment * affected endpoint, host, file path, component, or package when available * evidence captured during the run * proof-of-concept or approach details * attack flow graph when available * impact summary * remediation guidance * validation details or retest actions when available Use the evidence and proof-of-concept detail to reproduce the issue in a controlled environment before changing production systems. Review the evidence in the context of your application before accepting a finding's severity or conclusion. Record corrections through **Agent Context** or a **False Positive** decision when appropriate. Vulnerable-component findings may include advisory or CVE evidence when the affected component and version are available. ## Severity and CVSS MindFort uses severity to help teams prioritize triage quickly. Finding details show the severity label and the CVSS v3.1 score when available. Prioritize: 1. critical and high findings that are exploitable 2. findings with clear proof-of-concept evidence 3. issues that cross tenant, user, or role boundaries 4. findings affecting internet-exposed or privileged components ### Adjust a finding rating When severity overrides are enabled for your organization, open a red-team finding and select **Edit** beside its rating. Choose a severity and, optionally, a CVSS v3.1 score from 0.0 to 10.0 with one decimal place, then select **Save override**. Use **Restore MindFort rating** to return to the generated rating. Changing a rating does not resolve the finding; record your triage reasoning in a comment. Members whose only role is auditor cannot change ratings. ## Record a resolution decision When resolving a finding, choose the reason that matches your decision: * **Fix:** Record the remediation and how it was verified. * **Won't Fix:** Explain why your team is accepting or deferring the issue. * **False Positive:** Explain why the reported issue is not a vulnerability. This archives the finding as a false positive and requires a reason. A manually resolved finding is not the same as a successful retest. After deploying a fix, use [Retesting](/guides/retesting) to validate it against the target. ## Give agents feedback Use **Agent Context** in the finding details to add or edit feedback about accuracy, severity, evidence quality, or missing context. Give a specific explanation that future agents can use when investigating the target. Members whose only role is auditor can read existing feedback but cannot edit it. ## Bulk Actions For large queues, select multiple findings and apply batch actions: * resolve or reopen * archive or unarchive * create Linear or Jira tickets when connected * delete Available actions depend on the current tab and your permissions. ## Collaboration Flow 1. Assign owner. 2. Add implementation notes in comments. 3. Resolve the finding when remediation is ready for validation. 4. Retest and review the result and supporting evidence. ## API and MCP List findings programmatically with the same filters the UI uses: * [Findings API](/api-reference/findings) — `GET /v1/findings` (API key) * [MCP](/guides/mcp) — `list_findings` tool (OAuth) Use `status=ACTIVE&exclude_secured=true` to match the default **Open** tab, `status=RESOLVED` for the **Resolved** tab, `status=ARCHIVED` for the **Archived** tab, and `assessment_id` to scope results to one assessment run. # Connect GitHub, Linear, Jira, and Slack integrations Source: https://docs.mindfort.ai/guides/integrations Learn how to connect GitHub, Linear, Jira, and Slack to MindFort to patch findings, create tickets, and launch Agents from your team's tools. ## Overview MindFort integrations carry finding context into the tools your team already uses. Manage all integrations from **Settings > Integrations**. An upgraded plan and permission to manage integrations are required to connect them. Organization owners and admins have this permission; custom roles can also receive it. Create Linear issues from findings and choose a default team for new issues. Create Jira tickets from findings and map ticket status back to MindFort. Connect Slack to launch Agents from channels and configure routing rules. ## GitHub GitHub integration enables patching. When connected, you can generate a proposed fix pull request directly from the finding detail view. ### Connect 1. Go to **Settings > Integrations**. 2. Click **Connect** on the GitHub card. 3. Authorize the MindFort GitHub App and select the repositories you want to grant access to. ### Usage Once connected and linked to a target, **Patch** is available from its findings. Choose a linked repository and base branch to create a PR with a proposed fix. See the [Patching](/guides/patching) guide for full details. ### Configure Click **Configure** on the connected GitHub card to open your GitHub App installation settings, where you can add or remove repository access. ## GitHub security reviews GitHub also supports [Security Reviewer](/guides/security-reviewer) for automatic pull request security reviews. When the feature is enabled, configure repositories from **Security Reviewer** and inspect review results there. # Jira integration Source: https://docs.mindfort.ai/guides/integrations-jira Connect Jira to MindFort, create tickets from security findings, and map Jira status transitions back to the finding state in MindFort. Jira integration lets you create Jira tickets directly from findings and sync ticket status back to MindFort. ## Connect 1. Go to **Settings > Integrations**. 2. Click **Connect** on the Jira card. 3. Authorize MindFort with your Atlassian account. ## Configure After connecting, click **Configure** to: * Select the **default project** where new tickets are created. * Set up **status mapping** so Jira status transitions automatically update finding state in MindFort, such as mapping Jira statuses to Active or Resolved. ## Usage Open any finding and click **Create Jira Ticket** to push the finding details to Jira. Once a ticket exists, the button changes to **View Jira Ticket** with a link to the ticket and its current status. ## Interpret synchronized status Jira's Done category or the configured resolved status resolves the linked finding. New or in-progress categories, or the configured active status, reopen it so your team can resume triage. If automatic retesting is configured, an eligible resolution can queue validation. A resolved ticket is not proof that a deployed vulnerability is fixed; review the [retest result](/guides/retesting). # Linear integration Source: https://docs.mindfort.ai/guides/integrations-linear Connect Linear to MindFort, create issues from security findings, sync status changes, and track remediation without leaving the findings view. Linear integration lets you create Linear issues from findings for streamlined issue tracking. ## Connect 1. Go to **Settings > Integrations**. 2. Click **Connect** on the Linear card. 3. Authorize MindFort with your Linear workspace. ## Configure After connecting, click **Configure** to select the **default team** where new issues are created. ## Usage Open any finding and click **Create Linear Issue** to push the finding details to Linear. Once an issue exists, the button changes to **View Linear Issue** with a link and the issue's current state. ## Finding status synchronization A completed Linear issue resolves its linked finding. Canceling the issue resolves the finding as **Won't Fix**. Moving it back to an active workflow state reopens the finding so your team can resume triage. If automatic retesting is configured, an eligible resolution can queue validation. A resolved ticket is not proof that a deployed vulnerability is fixed; review the [retest result](/guides/retesting). # Slack integration Source: https://docs.mindfort.ai/guides/integrations-slack Connect Slack to MindFort, launch Agents by mentioning @MindFort in channels, and configure routing rules and alert preferences for findings. Slack integration lets your team launch MindFort Agents from Slack by mentioning `@MindFort` in connected channels. ## Connect 1. Go to **Settings > Integrations**. 2. Click **Connect** on the Slack card. 3. Authorize MindFort for your Slack workspace. ## Configure After connecting, click **Routing Rules** on the Slack card to configure where Slack-triggered Agents should route. Slack alert preferences are available from **Settings > Notifications** after Slack is connected. ## Usage Mention `@MindFort` in a connected Slack channel to launch an Agent from the conversation. Use routing rules to keep requests aligned with the right workspace or target. # Filesystem Source: https://docs.mindfort.ai/guides/knowledge-lakes Upload target reference material and browse the target files shared by MindFort users and agents, including notes, work, and threat models. ## Overview Open **Filesystem** to browse files for a target. Users and agents share this reference material across their work on that target. The `knowledge-lake` folder holds reference material you manage. Agent requests, notes, work, and threat models are available as read-only context. ## Add reference material 1. Open **Filesystem** from the sidebar. 2. Select a target. 3. Open its `knowledge-lake` folder. 4. Use **New folder** to organize your material, or **Upload files** to select files. Upload API specifications, architecture notes, application workflows, and other material that helps agents understand the target. Keep testing boundaries in the target's [scope and guardrails](/guides/scope-and-guardrails). ## Browse and manage files Select a folder to browse its contents. Open a file to preview supported content, or download it to inspect locally. Editable text files in `knowledge-lake` can be updated from the preview. You can delete files and folders in the writable area. Deleting a folder also deletes its contents; review the confirmation before continuing. Agent-generated context outside the writable area is read-only. If an upload fails, review the displayed error. For a name conflict, use a unique name or remove the existing file before retrying. ## Keep context current * Select the correct target before uploading. * Replace outdated reference material when the application changes. * Review agent notes and threat models alongside [Coverage](/guides/coverage) and [Findings](/guides/findings). # Writing Login Instructions Source: https://docs.mindfort.ai/guides/login-instructions Learn how to write clear, step-by-step login instructions to help MindFort agents navigate authentication and access areas behind the login. ## Purpose Login instructions tell MindFort agents exactly how to log into your target application using the stored credential. Without these instructions, agents may not find the correct login path or complete the full sign-in flow, which reduces authenticated coverage. ## What to Write Write plain, step-by-step login directions: 1. exact login URL or route 2. if login path differs from target root (example: target is `https://example.com`, login is `https://example.com/login`) 3. any required context values (example: org/workspace ID, tenant slug, environment selector) 4. exact actions to submit login 5. expected post-login page For Magic Link credentials, explain where to request the sign-in link and which page should appear after the link is opened. ## Good Example ```text theme={null} Target: https://example.com Login route: https://example.com/login Org ID: acme-security 1. Go to https://example.com/login 2. Enter Org ID: acme-security 3. Enter the stored username and password 4. Click Sign In 5. Confirm login at https://example.com/dashboard ``` ## Common Mistakes * only listing the main website URL * omitting redirects after sign-in * including outdated login paths * not mentioning required intermediate clicks # MCP (Model Context Protocol) Source: https://docs.mindfort.ai/guides/mcp Connect an AI agent to MindFort over MCP to manage authorized targets, assessments, findings, coverage, credentials, analytics, and reports. ## What You Can Do Connect Cursor, Claude Code, Codex, or another MCP client to MindFort and work with your organization's security program from your agent. The MindFort MCP server exposes an explicit, organization-scoped tool catalog for: * Browsing, creating, updating, and deleting authorized targets * Managing write-only test credentials for web applications and APIs * Reviewing coverage scenarios, run states, and linked findings * Discovering candidate targets when Discovery is enabled * Starting, monitoring, and canceling assessments * Browsing, triaging, commenting on, and retesting findings * Reading security metrics, distributions, aging, remediation, and health scores * Generating, polling, and downloading reports Your agent can work with data available to your MindFort account. Use resource IDs returned by MindFort instead of guessing identifiers. ## MCP Use Cases | Use Case | Example Prompt | | - | - | | **Check current posture** | `Show my current MindFort metrics, coverage gaps, and critical active findings.` | | **Monitor an assessment** | `List my active assessments and show the stage progress for the newest one.` | | **Investigate a finding locally** | `Pull this MindFort finding, inspect the relevant code, and explain the vulnerable path.` | | **Generate a local patch** | `Use the evidence and remediation advice to patch this finding in my working tree.` | | **Retest after deployment** | `Add a deployment note, start a retest, and poll the finding until it finishes.` | | **Prepare a report** | `Generate a condensed report for this target and give me the download URL when ready.` | | **Configure API testing** | `Show the target metadata and credential types required for authenticated API testing.` | | **Review coverage gaps** | `List incomplete coverage checks and summarize their latest run results.` | ## MCP vs. Platform Patching Use **Patching** when you want MindFort to generate a pull request directly from the platform. Use **MCP** when you want your local AI agent to combine MindFort evidence with your repository checkout, build system, and engineering conventions. ## Install ### Cursor [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=MindFort\&config=eyJ1cmwiOiJodHRwczovL2FwaS5taW5kZm9ydC5hcHAvbWNwIiwidHJhbnNwb3J0IjoiaHR0cCJ9) Or add the server to `.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "MindFort": { "url": "https://api.mindfort.app/mcp", "transport": "http" } } } ``` ### Claude Code ```bash theme={null} claude mcp add --transport http MindFort https://api.mindfort.app/mcp ``` Then run `/mcp` inside Claude Code to sign in. Or add the server to `.mcp.json`: ```json theme={null} { "mcpServers": { "MindFort": { "type": "http", "url": "https://api.mindfort.app/mcp" } } } ``` ### Codex ```bash theme={null} codex mcp add MindFort --url https://api.mindfort.app/mcp ``` Or add the server to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.MindFort] url = "https://api.mindfort.app/mcp" ``` ### Other MCP Clients Use the Streamable HTTP endpoint: ```text theme={null} https://api.mindfort.app/mcp ``` MindFort uses stateless Streamable HTTP: clients send MCP requests with `POST /mcp`. The legacy HTTP+SSE transport and the old `GET /mcp` stream and `DELETE /mcp` session methods are not supported. ## Sign In and Authorization MindFort MCP uses browser-based OAuth with your existing MindFort account. You do not need an API key. 1. Add the MindFort MCP server. 2. Complete the browser sign-in when your client prompts you. 3. Select the intended MindFort organization. 4. Ask the agent to call `get_current_context` and confirm the organization, role, and enabled capabilities. MCP access requires active organization membership and the applicable permissions and features. If your membership or permissions change, reconnect and confirm your access with `get_current_context`. The catalog depends on the member's role and organization features. Members whose only role is auditor have read-only access to permitted operations. Feature-gated tools and credential variants appear only when their organization has the corresponding feature enabled. MindFort does not expose billing administration, API-key administration, organization membership, or role administration over MCP. ## Start with Context To help your agent use the correct context and resource IDs, use this sequence: 1. Call `get_current_context` to confirm the selected organization and available capabilities. 2. Call `list_targets`, then `get_target` before target-specific work. 3. Reuse target, credential, assessment, finding, coverage check, and report IDs returned by MindFort. 4. Review tool warnings before starting active testing or performing destructive actions. 5. Poll asynchronous operations with their corresponding read tool. The server also exposes the fixed resource `mindfort://guides/start-here`. MCP clients that support resources can discover and read it for the compact operating sequence. For detailed semantics, use this documentation and the [agent-readable documentation index](https://docs.mindfort.ai/llms.txt). ## Capabilities and Feature Gating The tool catalog is explicit and may differ by organization. | Area | Typical workflow | | - | - | | **Targets** | `list_targets` -> `get_target` -> create, update, or confirmed deletion | | **Credentials** | List safe metadata; create, rotate, or delete write-only test credentials | | **Coverage** | Read current scenarios, run summaries, and linked findings | | **Discovery** | Configure discovery, run it, and review candidate targets when enabled | | **Assessments** | `run_assessment` -> poll `get_assessment` -> inspect findings | | **Findings** | List/get, update lifecycle, comment, override severity, retest, and inspect patch summaries | | **Analytics** | Read counts, distributions, health, history, timeseries, remediation, SLA, and aging | | **Reports** | `create_report` -> poll `get_report` -> `download_report` | ### Complete tool catalog The baseline and feature-gated catalog contains the following tools. Call `get_current_context` first because feature-gated tools may be absent for the selected organization. | Area | Tools | | - | - | | **Context** | `get_current_context` | | **Targets** | `list_targets`, `get_target`, `create_target`, `update_target`, `delete_target` | | **Credentials** | `list_target_credentials`, `create_target_credential`, `update_target_credential`, `delete_target_credential`, `generate_target_email_credential`, `check_email_mfa`, `get_authenticator_2fa_code`, `get_sms_credentials_access`, `list_sms_credential_countries`, `check_sms_code` | | **Coverage** | `list_coverage_checks`, `get_coverage_overview` | | **Discovery** | `get_discovery_status`, `update_discovery_schedule`, `update_discovery_context`, `start_discovery_run`, `cancel_discovery_run`, `list_discovery_suggestions`, `accept_discovery_suggestion`, `dismiss_discovery_suggestion` | | **Assessments** | `list_assessments`, `get_assessment`, `run_assessment`, `cancel_assessment` | | **Assessment schedules** | `list_assessment_schedules`, `get_assessment_schedule`, `create_assessment_schedule`, `update_assessment_schedule`, `delete_assessment_schedule`, `trigger_assessment_schedule`, `pause_assessment_schedule`, `resume_assessment_schedule` | | **Findings** | `list_findings`, `get_finding`, `update_finding_status`, `update_finding_statuses`, `update_finding_severity`, `retest_finding`, `add_finding_comment`, `list_finding_comments`, `edit_finding_comment`, `delete_finding_comment`, `list_finding_patches`, `get_patch_count` | | **Analytics** | `get_finding_counts`, `get_severity_distribution`, `get_target_health_score`, `get_category_distribution`, `get_severity_score_history`, `get_current_security_metrics`, `get_security_metrics_timeseries`, `get_remediation_metrics`, `get_sla_metrics`, `get_finding_aging` | | **Reports** | `create_report`, `list_reports`, `get_report`, `download_report` | Feature-gated capabilities include: * `discovery`: discovery status, context, schedules, runs, and suggestions * `network-targets`: network target creation and assessment inputs * `sms-credentials`: SMS credential variants, provisioning metadata, and code checks * `finding-severity-overrides`: setting severity overrides; clearing an existing override remains available If your available features or permissions change, reconnect or start a new chat to refresh the tools available to your agent. ## Targets and Credentials Web application and API targets require an HTTP(S) `web_domain`. Network targets require an `ip_address` and are available only when enabled for the organization. Targets created through REST or MCP start unverified; complete ownership or network verification in the MindFort dashboard before active testing. Credential list and detail reads return metadata only; they do not return passwords, API-key values, or TOTP seeds. Dedicated authentication helpers can return a temporary code or login URL, and email provisioning returns a pending inbox ID for credential creation. For API targets, `api_key` credentials require nonblank target-level `api_auth_instructions` that explain: * The validation route and HTTP method * The required request shape * Where the key is placed, such as a bearer token, header, query parameter, or JSON field * The expected successful response Secrets are write-only. Rotate a secret through the update tool instead of expecting to read it back. ## Assessments and Stage Progress Starting an assessment begins active security testing and may consume plan capacity. Use only a target the user intends to test. Use `stage_progress` in the `get_assessment` response to track assessment stages: * `NOT_STARTED` means no state has been recorded. * `RUNNING` or `ACTIVE` means work is in progress. * Other values are terminal stage outcomes. * Active testing stages may include status, attempt, and timing fields. Top-level `created_at`, `updated_at`, `started_at`, and `completed_at` describe the full run. Failed runs may include a `failure_reason` explaining the problem. `cancel_assessment` accepts only the assessment ID. Record any cancellation context in your own workflow. ## Findings and Retests The `list_findings` tool accepts the same filters as `GET /v1/findings`. | Argument | Default | Description | | - | - | - | | `target_id` | — | Limit to one target | | `assessment_id` | — | Limit to one assessment run | | `status` | `ACTIVE` | `ACTIVE`, `RESOLVED`, or `ARCHIVED` | | `exclude_secured` | `false` | Omit informational secured probes when `true` | | `severity` | — | `critical`, `high`, `medium`, `low`, or `secured` | | `sort_by` | `severity` | `severity` or `created_at` | | `limit` | Tool-specific | Bounded page size | | `cursor` | — | Opaque continuation cursor from the previous result | Use `total` for the full matching count rather than the first page length. To match the dashboard Open tab, use `status=ACTIVE` and `exclude_secured=true`. Retests are asynchronous and may be started for `ACTIVE`, `RESOLVED`, or `ARCHIVED` findings. Poll `get_finding`: * `QUEUED` or `RUNNING`: execution is still active. * `FAILED`: `retest_failure_reason` explains why execution could not complete. * `COMPLETED`: validation finished and the result was applied. A result indicating the issue is fixed under the tested conditions sets the finding to `RESOLVED`; a result indicating it remains reproducible sets it to `ACTIVE`. See [Findings API](/api-reference/findings) for REST examples and field details. ## Pagination MCP list tools use opaque cursors rather than REST offsets. When a result includes `next_cursor`, pass it back unchanged with the same filters. Cursors are bound to the operation and filter set, so changing filters requires starting a new pagination sequence. `tools/list` returns the complete authorized catalog and is not paginated. ## Errors and Sensitive Actions Tool failures include a stable error code, safe message, retry guidance when applicable, and a request ID for support correlation. Validation errors may also include field-level details. If the connection returns HTTP `429 Too Many Requests`, wait for the `Retry-After` interval before retrying and reduce polling frequency. Common actionable codes include: * `target_not_verified` * `api_auth_instructions_required` * `assessment_already_running` * `assessment_credits_insufficient` * `assessment_queue_loading` * `retest_already_running` Destructive tools have prominent warnings and MCP destructive annotations. Invoking the tool performs the action after normal validation; MindFort does not add a second approval handshake. Review target names, resource IDs, and warnings before deletion, cancellation, archival, or active testing. ## Troubleshooting Confirm the URL is exactly `https://api.mindfort.app/mcp`, your network allows HTTPS, and your client supports Streamable HTTP. Restart the client and try again. Clear the MCP connection and add it again. In Claude Code, run `/mcp`, select MindFort, and re-authenticate. If the issue continues, contact [support@mindfort.ai](mailto:support@mindfort.ai). Call `get_current_context` to confirm the selected organization and its public feature flags. Then reconnect or start a new chat so the client refreshes tool discovery. This is expected when `list_findings` uses the default `status=ACTIVE`. Pass `status=RESOLVED` or `status=ARCHIVED` to browse those lifecycle states. The dashboard Open tab hides informational secured probes by default. Pass `exclude_secured=true` and `status=ACTIVE` to match it. Use `assessment_id` when comparing one assessment. Pass `next_cursor` back unchanged with the same tool and filters. Start over without a cursor after changing filters. ## Coverage and discovery Use `list_coverage_checks` for individual scenarios and `get_coverage_overview` for aggregate counts. Keep `covered`, `failing`, `incomplete`, `in_progress`, and `not_run` separate when summarizing results. Coverage is read-only; there are no tools to create, edit, or rerun a check. [Discovery](/guides/discovery) proposes candidate targets. Accepting a suggestion creates a target; inspect its verification state before starting testing. Discovery tools appear only when the feature is enabled. # Onboarding & Setup Source: https://docs.mindfort.ai/guides/onboarding-setup Learn how to complete MindFort onboarding — create an organization, add a target, verify domain ownership via DNS, and prepare for your first run. ## Setup Flow MindFort only allows work email addresses. Personal email accounts (such as Gmail, Outlook, or Yahoo) cannot be used to sign up for or sign in to the platform. Use your company email when creating your account. When you first sign in, complete onboarding in this order: 1. Create or join an organization. 2. Add your organization details. 3. Choose a target type and add its details. 4. Optionally add credentials and authentication instructions. 5. Choose a verification or onboarding method. 6. Optionally connect GitHub. 7. Continue to the dashboard. ## Step 1: Organization * Create a new organization if you are starting fresh, then enter the organization name and how you heard about MindFort. A primary phone number is optional. * If you were invited, switch into the correct organization before continuing. ## Step 2: Add Domain and Target Choose **Web Application** or **API**, then provide: * target name * target URL * target description * optional credentials and login instructions If you add credentials, authentication instructions are required. Network targets can be added later from **Target Inventory** when available for your organization. ## Step 3: Choose Setup Method You can continue with: * **Auto Setup** * **Manual Configuration** * **Book a Call** * **Skip this step** ## Step 4: Verify Domain Ownership For manual verification: 1. Copy the DNS TXT token shown in setup. 2. Add it to your DNS provider. 3. Return to MindFort and click **Verify Domain**. You can finish onboarding without verification, but assessments remain unavailable for the target until verification is complete. ## Step 5: Connect GitHub (Optional) Connect GitHub if you want to link source repositories for White-Box assessments, Security Reviewer, or patch pull requests. You can also do this later from **Settings → Integrations**. ## Step 6: Final Readiness Check Before your first assessment: * target shows verified status * credentials are valid (if added) * login instructions are current (if authenticated testing is needed) ## First Run After Setup Go to **Assessments** and start your first run. Then move to **Findings** for triage and **Reporting** for report generation. # Patching Source: https://docs.mindfort.ai/guides/patching Learn how to generate proposed fix pull requests for security findings using the GitHub integration, then review, validate, and merge. ## Overview Patching turns a finding into a proposed pull request against the repository and branch you select, giving engineers a concrete change to review and validate. ## Patching Use Cases Use patching when you want MindFort to turn finding context into a proposed code change. | Use Case | How It Helps | | - | - | | **Address a confirmed finding** | Generate a proposed fix PR from the finding's evidence, impact, and remediation advice. | | **Speed up remediation review** | Give engineers a concrete patch to inspect instead of starting from a blank ticket. | | **Handle repeated bug classes** | Propose changes for similar access-control, validation, or configuration issues after a pattern is understood. | | **Prepare for retest** | Deploy reviewed changes, then re-run an assessment or retest to check whether the issue still reproduces. | | **Connect security and engineering workflows** | Keep the finding linked to the generated PR so teams can move from evidence to code review. | Patching is best for platform-generated pull requests. If your team wants to use a local AI copilot inside its own checkout, connect the copilot through [MCP](/guides/mcp) so it can read MindFort finding evidence and remediation advice from the platform. ## Prerequisites * Connect GitHub under **Settings → Integrations**. * [Link at least one enabled repository to the target](/guides/targets#link-source-repositories). ## Create a Patch 1. Open a finding from the **Findings** view. 2. Select **Patch** in the finding actions. 3. Select a linked repository. 4. Select the **base branch** the PR should target. 5. Click **Create PR**. MindFort will begin generating the patch. While the patch is being created, the button shows a "Patching" status indicator. Once complete, a **View PR** link appears so you can review the changes on GitHub. ## Review and Merge After the PR is created: 1. Review the proposed changes on GitHub. 2. Run your CI/CD checks as usual. 3. Merge when satisfied. ## Recommended Process 1. Start with high- and critical-severity findings. 2. Always review the generated PR before merging — treat it as a starting point. 3. Deploy the reviewed changes, then re-run an assessment or retest to check whether the reported issue still reproduces. ## Patch status and finding status Patch status tracks the generated pull request. A merged patch does not, by itself, prove that a deployed vulnerability is fixed or mark the finding resolved. When the organization has automatic retesting after patch merge configured, the finding shows the queued or scheduled validation and its result. See [Automatic retest status](/guides/retesting#automatic-retest-status). # Platform Overview Source: https://docs.mindfort.ai/guides/platform-overview Learn where each MindFort feature lives in the platform — findings, targets, assessments, agents, coverage, analytics, reporting, and workspace settings. ## Main Navigation * **Overview**: high-level security status and activity * **Assessments**: active, scheduled, and historical assessments * **Findings**: search and manage findings across all targets * **Coverage**: review security scenarios, current run states, and linked findings * **Agents**: run directed security work, reuse templates, and manage agent schedules * **Analytics**: review organization-wide security metrics and trends * **Target Inventory**: manage targets, verification, scope, credentials, and login instructions * **Filesystem**: manage target reference material and browse shared agent context * **Reporting**: generate and manage downloadable reports * **Settings**: account, team, billing, notifications, integrations, WAF, API keys, status * **Billing**: directly accessible from the sidebar for quick access to credits, subscription, and invoices Depending on your organization's access, [**Security Reviewer**](/guides/security-reviewer) may also appear. ## Assessments vs. Agents **Assessments** are designed for broad, repeatable penetration testing within the configured scope and available access. Configure the target and method, start the run, and review the resulting evidence and findings. **Agents** are for directed security work. Select a target, describe what you want investigated, and monitor the run. Agents are useful for targeted investigations, custom checks, and follow-up work that may need your input. ## Choose the Right Workflow | Goal | Use | | - | - | | Establish or refresh broad security coverage | **Assessments** | | Investigate a specific question | **Agents** | | Check a deployed fix for an existing finding | **Retesting** | | Review pull request code changes | **Security Reviewer** | | Prioritize, assign, and collaborate on issues | **Findings** | | Turn a finding into engineering work | **Linear**, **Jira**, **Patching**, or **MCP** | | Identify gaps and blocked checks | **Coverage** | | Track trends and remediation progress | **Analytics** | | Share results with stakeholders | **Reporting** | ## How the Workflow Fits Together MindFort connects authorized target setup, broad discovery, focused investigation, remediation, validation, and stakeholder reporting in one workflow. Use assessments for broad discovery, Agents for directed follow-up work, MCP for working with findings from supported coding assistants, and reports for sharing results with stakeholders. ## Recommended Operating Rhythm 1. Keep target configuration current. 2. Run assessments regularly. 3. Triage findings and assign owners. 4. Remediate through tickets, patching, or your connected developer workflow. 5. Retest and validate resolved findings. 6. Review coverage and trends, then publish regular reports. ## Core Security Artifacts * **Scope and guardrails** define what agents may test and which areas require extra care. * **Credentials and login instructions** help agents access authenticated areas. * **Assessment logs** show endpoint and note evidence recorded for an assessment run. * **Findings** capture severity, CVSS score where available, evidence, proof-of-concept detail, and remediation guidance. * **Reports** package target-level results for stakeholders. ## Access Notes Some sections depend on role, plan, or billing status. If a feature is unavailable, confirm: * user role permissions * active subscription state * feature availability for your organization # Reporting Source: https://docs.mindfort.ai/guides/reporting Learn how to generate, download, and manage MindFort security assessment reports to share vulnerability results with stakeholders and leadership. ## Generate a Report Reporting requires a paid plan and is unavailable on the Free plan. 1. Open **Reporting**. 2. Select **Generate Report**. 3. Select a target. 4. Choose **Full** or **Condensed** detail. 5. Optionally include secured findings, resolved findings, or both. 6. Start generation. Reports include active findings by default and use the finding details available at generation time. Choose **Full** when security or engineering reviewers need detailed finding context. Choose **Condensed** when stakeholders need a shorter overview of the current results. ## Report Contents Reports can include: * target summary * report metadata * severity breakdown * finding list * finding impact * evidence summaries * remediation guidance * methodology and stakeholder summary language Use reports after assessment cycles, after major remediation work, and before customer or compliance reviews. ## Manage Reports From the reports table, you can: * search by target * sort by target/date * review detail level, included finding states, and generation status * refresh to check in-progress reports * download completed reports * delete old reports ## Report Formats When a report finishes generating, select **Download** from its row. ## Recommended Process 1. Generate after major assessment cycles. 2. Download and share with stakeholders. 3. Re-run or retest important findings after remediation. 4. Generate an updated report that reflects the current status. 5. Keep only required historical reports in the table. # Retesting Findings Source: https://docs.mindfort.ai/guides/retesting Learn how to retest MindFort findings to check whether a reported vulnerability still reproduces against the live target after remediation. ## Overview Retesting checks whether a previously reported red-team finding still reproduces after you apply a fix. MindFort attempts to reproduce the reported issue against the live target and updates the finding with the result. Use a retest after your team deploys a remediation. A retest focuses on the existing finding; it does not replace a full assessment when you need broader coverage of the target. Retesting is available for red-team findings on upgraded plans. Each finding retest uses one credit. ## Before You Retest Confirm that: * the remediation is deployed to the target environment * the target is reachable by MindFort * any credential required to reproduce the finding is still valid * the finding is not already queued or being retested If the original finding requires authentication, MindFort uses the finding's saved credential selection, including a secondary credential when required, to prepare an authenticated session. You do not need to provide credentials again when starting the retest. ## Retest One Finding 1. Open **Findings** from the sidebar. 2. Select the target that contains the finding. 3. Open the finding details. 4. Click **Retest** in the finding actions. The button shows the one-credit cost. After you submit the request, the finding displays **Retest queued** and starts automatically when capacity is available. ## Retest Multiple Findings You can queue several eligible findings from the same target: 1. Open the target's **Findings** view. 2. Select the red-team findings you want to verify. 3. Click **Retest Issues** in the bulk action bar. MindFort reports how many retests were queued, skipped, or failed to queue. A finding is skipped when it is not eligible for a new retest, such as when another retest is already active. To retest every open finding for a target, use the retest action in the findings toolbar. The credit indicator shows the number of open findings that will be submitted. Retest only after the relevant fixes are deployed. Starting the same checks before deployment consumes credits without validating the remediation. ## Understand Retest Status The finding details show the current or most recent retest state. | Status | Meaning | | - | - | | **Retest queued** | The request was accepted and will start automatically when a retest slot is available. | | **Retest in progress** | MindFort is validating the finding against the live target. | | **Confirmed fixed** | The retest indicates that the issue no longer reproduces under the tested conditions. The finding moves to **Resolved**. | | **Still exploitable** | The issue reproduced during the retest. The finding remains **Active**. | | **Retest couldn't complete** | MindFort could not reach a security outcome. Review the displayed reason and try again after resolving it. | | **Previous retest timed out** | The earlier run is stale. Start a new retest to get a fresh result. | A failed or incomplete retest does not mean the vulnerability is fixed. Only **Confirmed fixed** resolves the finding. Review the retest evidence to understand the conditions tested and the basis for the result. ## Capacity and Queueing MindFort queues accepted retests and starts them as execution capacity becomes available. If you cannot start a retest, review the displayed reason and retry when capacity is available. Queued work starts automatically. You can leave the finding page and return later to review the result and completion time. ## Troubleshooting If a retest cannot complete: * confirm the target is online and reachable * verify the remediation has been deployed to the tested environment * update expired or changed [authentication credentials](/guides/authentication-credentials) * check that login instructions still match the target's current flow * wait for available capacity if the retest action is disabled * start a new retest when the finding reports that the previous run timed out If the issue continues, contact [support@mindfort.ai](mailto:support@mindfort.ai) with the finding ID and the failure reason shown in MindFort. ## Recover from an authentication failure If a retest fails because a credential could not authenticate, was deleted, or is unavailable, you can choose a replacement from the finding details: 1. Open the finding and read the retest failure message. 2. Select **Choose another credential**. 3. Choose a stored credential for the same target. The picker shows **Verified**, **Verification failed**, or **Not verified** to help you check its readiness. 4. For a finding that requires two accounts, review **Primary credential** and **Secondary credential**. You can replace either account, but the two selections must be different. 5. Select **Retest** to queue a new attempt. If no credentials are saved, add one in **Target Inventory > Stored Credentials**, then return to the finding. Update incorrect account details or login instructions and [verify the credential](/guides/authentication-credentials#verify-credentials) before retrying. Your selections also apply to future retests of this finding. The original finding evidence is preserved. **Choose another credential** appears after an authentication or unavailable-credential failure and requires permission to retest findings. Review the failure message for billing information. Authentication or unavailable-credential failures can report that you were not charged. ## Automatic retest status An organization can configure automatic retesting in **Settings > Features**. Two separate settings apply: * **Auto-Retest Mode** validates eligible red-team findings after they are resolved, including resolution through linked tickets. The finding is already resolved when validation is queued; a result that remains vulnerable reopens it. **Won't Fix** resolutions, including canceled Linear issues, do not trigger this mode. * **Auto-retest after patch merge** checks a MindFort patch after its pull request merges. Merging the patch alone does not resolve the finding. Resolution requires a retest result indicating the issue is fixed under the tested conditions. Patch-merge retests can have an **After Merge Retest Time Delay** from 0 to 60 minutes to allow deployment to finish. A delayed run shows **Retest scheduled after patch merge** and its scheduled time. Queuing still depends on access, credentials, and retest eligibility. An incomplete retest is not confirmation of a fix, even if a manual action or ticket transition already set the finding to Resolved. ## Next Steps * Review the complete [finding lifecycle](/guides/findings). * Generate a proposed fix with [Patching](/guides/patching). * Run a broader [assessment](/guides/assessments) when you need coverage beyond one finding. # Scope and Guardrails Source: https://docs.mindfort.ai/guides/scope-and-guardrails Define the authorized testing boundaries, rate limits, and agent behavior rules that tell MindFort what it can test and which actions require extra care. Scope and guardrails tell MindFort what it is authorized to test and which actions require extra care. Configure them before starting assessments or Agents. ## What Scope Controls Use scope configuration to define: * primary domains and application URLs * additional allowed domains or routes that are part of the same target * in-scope systems agents should include * out-of-scope systems agents should exclude * important tenant, workspace, account, or environment values * authentication context and credential role boundaries Keep the target scope as specific as possible. A precise scope gives agents stronger context and helps reduce noisy exploration. ## Common Scope Patterns | Pattern | Use When | | - | - | | **Single application domain** | The target lives under one domain such as `https://app.example.com`. | | **Marketing plus app domain** | Login begins on one domain and redirects into another application domain. | | **Tenant-specific app** | The application requires an org slug, tenant ID, workspace ID, or account selector. | | **Authenticated-only areas** | Sensitive routes should only be tested after the agent is signed in with an approved test credential. | | **Excluded operational paths** | Routes such as billing, destructive admin actions, production email sends, or customer-impacting workflows must be excluded or constrained with rules. | ## Guardrail Types MindFort agents use guardrails to guide testing within approved boundaries: * **Rate Limiting** controls agent request pacing with Auto, Aggressive, Reduced, and Extreme Stealth modes. * **Scope** stores Include and Exclude entries for domains, IPs, CIDRs, routes, or other testing boundaries. * **Rules** store additional constraints for agent behavior. * **Custom Values** store target-specific context agents should know while testing. ## Configure Scope 1. Open **Target Inventory**. 2. Select the target. 3. Open the **Guardrails** tab. 4. Set **Rate Limiting** if the default automatic pacing is not appropriate. 5. Add **Include** entries for systems that agents should test. 6. Add **Exclude** entries for systems that agents must avoid. 7. Add **Rules** for behavior constraints such as avoiding destructive actions. 8. Add **Custom Values** for context such as `tenant_slug`, `workspace_id`, `organization_id`, or `environment`. 9. Save changes before starting an assessment or Agent. The Scope modal supports bulk entry for Include and Exclude items. Add one domain, IP, CIDR, route, or other scoped item per line. ## Examples ### Tenant-Aware SaaS App ```text theme={null} Target: https://app.example.com Login route: https://app.example.com/login Tenant slug: acme-security Include: /dashboard, /settings, /api Exclude: /billing, /admin/delete-account Rule: Do not trigger production emails or payment flows. ``` ### Multi-Domain Login Flow ```text theme={null} Target: https://app.example.com Login starts at: https://login.example.com Include domains: app.example.com, login.example.com Expected post-login page: https://app.example.com/dashboard ``` ## Before Launch Confirm: * the target is verified * stored credentials are dedicated test accounts * login instructions include every redirect and required intermediate step * include and exclude entries are current * behavior rules cover sensitive workflows * WAF allowlisting is complete if your infrastructure filters automated traffic For authentication setup, see [Authentication & Credentials](/guides/authentication-credentials). For firewall setup, see [WAF Whitelisting](/guides/waf-whitelisting). # Security Reviewer Source: https://docs.mindfort.ai/guides/security-reviewer Connect GitHub repositories for automatic pull request security reviews, manage review configurations, and inspect results in MindFort. ## Overview Security Reviewer reviews pull requests and tracks their security findings in MindFort. Use it to review code changes during development, alongside [assessments](/guides/assessments) of your running application. Connecting GitHub requires an upgraded plan and permission to manage integrations. Organization owners and admins have this permission; custom roles can also receive it. ## Enable reviews 1. Open **Settings > Integrations** and connect GitHub. 2. Grant the MindFort GitHub App access to the repositories you want reviewed. 3. Open **Security Reviewer**. 4. Find the repository in **Repositories** and select **Enable**. 5. Confirm **Enable code review**. This enables security reviews of code changes. Reviews apply to pull requests targeting any branch in that repository; you do not need a separate configuration for each branch. ## Review results The **Reviews** section shows pull request review activity and outcomes. Open a review to inspect its findings and progress, then follow the pull request link to review the code on GitHub. New configurations also post a review summary on GitHub. Read each finding's evidence and remediation guidance before deciding how to address it. A code review focuses on the submitted changes and available context; use an assessment when you need broader testing of the application. ## Request another review from GitHub On an open pull request that is ready for review, post a new conversation comment containing: ```text theme={null} @mindfort run review ``` The repository must have reviews enabled, and you need GitHub write, maintain, or admin access. Draft pull requests are not reviewed until they are ready. Review requests remain subject to your organization's plan and available credits. ## Incomplete reviews and limited coverage Read the GitHub summary and check result before treating a review as complete. A **Review incomplete** message means MindFort could not finish validating one or more potential findings. Any verified findings already published still need attention. For large pull requests, the summary may identify files or changes that were not reviewed. Do not treat a review with omitted changes as coverage of the entire pull request. Omitted changes are not automatically retried on later pushes; split large changes into smaller pull requests or contact support for help getting the remaining changes reviewed. ## Manage configurations Use **Disable** to stop a configuration from initiating future reviews, and **Enable** to turn it back on. Use **Delete configuration** when you no longer need the configuration. To change which repositories MindFort can access, open the GitHub integration configuration and update the GitHub App installation permissions. ## Troubleshooting * **A repository is missing:** Confirm that the connected GitHub App installation has access to it. * **Reviews are not starting:** Check that the repository configuration is enabled and the organization's billing state permits reviews. * **A review fails:** Open its details and inspect the reported failure before retrying or contacting support. Use [Patching](/guides/patching) to generate a proposed fix for a finding, or [MCP](/guides/mcp) to investigate it in your own checkout. # Settings and Billing Source: https://docs.mindfort.ai/guides/settings-and-billing Learn how to manage MindFort workspace settings — profile, team access, billing and credits, notifications, integrations, WAF, and API keys. ## Settings Tabs ### Profile Use **Settings → Profile** to update personal account and security settings. ### Team Use **Settings → Team** to manage members and organization access. ### Billing Use **Settings → Billing** to view credits and target balances, manage your subscription and payment method, purchase additional credits or target capacity, and review invoices. Admin access is required. Enterprise plans include custom assessment credit pricing, SSO/SAML, priority assessments, and dedicated support. Billing is also accessible directly from the sidebar for quick access. ### Notifications Use **Settings → Notifications** to control delivery preferences. ### WAF Configuration Use **Settings → WAF Configuration** to copy current allowlist IPs. ### Integrations Use **Settings → Integrations** to connect or disconnect supported tools. Connected integrations enable additional actions throughout the platform, such as creating linked issues from findings, requesting patches, or launching Agents from Slack. An upgraded plan and permission to manage integrations are required to connect integrations. See [Integrations](/guides/integrations) for details. ### Features **Settings > Features** shows the organization's automatic retest settings. These settings control validation after finding resolution or patch merges; see [Retesting](/guides/retesting#automatic-retest-status) for how their results affect finding status. Owners, admins, and members with permission to manage integrations can change these settings. ### Status Use **Settings → Status** for current platform health. ### API Keys Use **Settings → API Keys** to create and manage keys for API usage. This requires permission to manage API keys. API keys are organization-scoped. Rotate keys regularly and remove keys that are no longer used by CI/CD systems or approved tools. If Billing or API Keys shows an access-denied message, use the Settings tabs to return to a page you can access. Ask an organization owner or admin for the required access. ## Setup Checklist for Admins 1. Confirm billing and plan state. 2. Invite required team members. 3. Configure integrations. 4. Configure notification preferences. 5. Share WAF allowlist with infrastructure owners. 6. Create API keys only for the systems that need them. ## Credits and usage-based billing The assessment form displays the cost before you start: Balanced uses 200 credits, Deep uses 400, and Ultra uses 800. A finding retest uses one credit. Starter and Pro customers can purchase additional credits and enable usage-based billing. When enabled, assessments can continue after prepaid credits are exhausted; usage beyond the prepaid balance is billed. Review the displayed rates and billing period before enabling it. Included plan credits may reset each billing period. Check **Billing** for your current balance, subscription, usage, and invoices. ## Feature access Agents, retesting, reporting, and connecting integrations require an upgraded plan. Organization features can impose additional access requirements; for example, Security Reviewer appears only when enabled for your organization. Scheduled assessments are available on all plans, subject to the target's readiness and available credits. ## Auditor access Members whose only role is auditor have read-only access to permitted security views, including Overview, Assessments, Findings, Target Inventory, and Coverage. They cannot start runs or change findings. Filesystem, Agents, Analytics, and administrative actions are not available to members with only the auditor role. # Targets Source: https://docs.mindfort.ai/guides/targets Learn how to add and verify Web Application, API, and available Network targets, then manage credentials, scope, and target details. ## Add a Target Only organization admins can add targets. 1. Go to **Target Inventory**. 2. Select **Add Target** and choose the target type. 3. Enter the required target name, address, and description. 4. Optionally configure authentication. 5. Review the configuration and complete the applicable verification step. The guided flow covers **Target Type**, **Target Details**, **Authentication**, **Review**, and **Verify Target**. ### Target URLs with a path Include a path when it is part of the application or API address you want tested, such as `https://app.example.com/portal` or `https://api.example.com/v1`. Review the target's [scope and guardrails](/guides/scope-and-guardrails) to specify included and excluded areas. ## Verify a Web Application or API 1. Open target details. 2. Go to the DNS section. 3. Copy the TXT verification token. 4. Add it in your DNS provider. 5. Return and run **Verify**. A target must be verified before it can be assessed. ## Network Targets When Network targets are available for your organization, enter the authorized IP address. Network targets do not use DNS verification or stored credentials. After creating one, select **Contact Support** on the target to request approval before running an assessment. ## Manage Target Details From the target detail page, you can: * edit target name and description * edit login instructions * add, edit, and delete stored credentials * add, edit, and delete target values (key-value context fields) * review verification state ## Target Scope Target details define the default testing scope for assessments and Agents. Keep the target address, login instructions, credentials, and target values current so the authorized boundary is clear. Use target values for context that is required to stay in scope, such as: * tenant slug * organization ID * workspace ID * environment name * account number * required environment setting or region selector Document any included or excluded areas before launching a run. For detailed scope and guardrail guidance, see [Scope and Guardrails](/guides/scope-and-guardrails). ## Credentials in Target Details In **Stored Credentials**, you can: * add new credentials * edit existing credentials * remove credentials Use dedicated test credentials only. ## Login Instructions In **Login Instructions**, document the exact login path to help MindFort agents authenticate and test areas behind login. ## Delete Target Use **Delete Target** only when you intentionally want to remove this target from active use. ## Link source repositories White-box assessments and patching use repositories associated with the target. 1. Connect GitHub in **Settings > Integrations** and grant access to the repository. 2. Open the target in **Target Inventory**. 3. Find **Associated Code Repositories**. 4. Select the repository, branch, and folder. Use `/` for the repository root. 5. Select **Add**. Keep the linked branch and folder aligned with the application you intend to assess. Repository access depends on the GitHub App installation and your organization permissions. # Agents Source: https://docs.mindfort.ai/guides/tasks Learn how to run directed security testing with MindFort Agents, save reusable prompt templates, and automate recurring runs on your targets. ## What Agents Are For Unlike assessments, which run broad autonomous penetration tests, Agents let you direct a specific security investigation. Select a target, describe what you need, monitor progress, and provide input when requested. You can select optional stored credentials for authenticated work and review the result alongside the rest of the target's security activity. Use Agents for targeted follow-up work, repeated checks, and investigations that benefit from human review. ## Agent Use Cases Use Agents for targeted security work such as: | Use Case | Example Prompt | | - | - | | **Retest a fix** | `Retest the resolved checkout IDOR finding and confirm whether the fix blocks cross-user access.` | | **Deep-dive a finding** | `Use the evidence from this finding to determine the likely root cause and propose the next validation steps.` | | **Authenticated workflow testing** | `Log in with the stored test credential and check whether billing settings are exposed to the wrong role.` | | **Regression checks after deploy** | `After the latest release, rerun targeted tests against the password reset and invite flows.` | | **Recurring focused check** | `Check the staging target for exposed admin routes, staying inside the configured include and exclude scope.` | | **Customer or audit prep** | `Summarize the currently resolved findings, remaining open risk, and evidence that should be included in the next report.` | For recurring work, save the request as a template and schedule it to run automatically. ## When to Use Agents Use **Agents** when you want directed security work against a target with optional stored credentials, live progress, and review points. Use **Assessments** when you want broad testing across a target. Use **Patching** when you want MindFort to generate a pull request from a finding. Use **MCP** when you want your own local AI copilot to read MindFort findings, investigate in your local codebase, and help remediate from inside your editor. ## Create and Run an Agent 1. Open **Agents**. 2. Select **New Agent**. 3. Select target. 4. Optionally select stored credentials. 5. Describe the work, or choose a template. 6. Run the agent. ## During Execution During a run, use **Chat**, **Plan**, **Docs**, **Logs**, and **Outcome** to follow progress and review results. You can monitor: * live logs and status * generated plan steps * approval prompts when input is required * final outcome/report content ## Save and Reuse Templates Use templates for repeated workflows: * create a template from an agent request * run a template against a selected target ## Agent Schedules Agents support schedule automation with: * one-time * daily * weekly * monthly When creating a schedule, set: * target * optional credential * frequency * date/time fields * timezone ## Manage Existing Agent Schedules From Agent scheduling controls, you can: * pause schedules * resume schedules * delete schedules ## Access and shared context Agents require an upgraded plan. Keep the target's credentials, instructions, and reference material current before starting work. Use [Filesystem](/guides/knowledge-lakes) to manage target reference files and inspect agent notes. For a deployed fix to an existing finding, use [Retesting](/guides/retesting) to record a validation result directly on that finding. # Test Targets for Evaluation Source: https://docs.mindfort.ai/guides/test-targets Learn how to evaluate MindFort using non-production test targets, dedicated test credentials, and environments without sensitive live data. ## Recommended Approach Use non-production targets for evaluation and team onboarding. ## Minimum Checklist * dedicated test environment * dedicated test credentials * no sensitive production data * DNS control for domain verification ## Evaluation Flow 1. Add target. 2. Verify domain. 3. Add credentials and login instructions. 4. Run assessment. 5. Review findings and generate report. ## Do Not Use * unauthorized third-party systems * production credentials tied to real users * environments containing regulated live data without approval # WAF Whitelisting Source: https://docs.mindfort.ai/guides/waf-whitelisting Learn how to allowlist MindFort's IP addresses in your WAF or firewall to reduce blocked assessment traffic. ## Get the Current IP List Always copy the current list from **Settings → WAF Configuration** in the app. ## Configure Your WAF/Firewall 1. Add each MindFort IP to your allowlist. 2. Ensure your security layers do not block assessment traffic from those IPs. 3. Save and deploy your rule changes. 4. Run a new assessment to confirm access. ## If assessments are slow or incomplete Recheck: * IP allowlist entries * rule priority/order * additional network controls in front of the app For provider-specific help, contact your infrastructure team with your current WAF rule set. # Welcome to MindFort Source: https://docs.mindfort.ai/index Get started with MindFort — onboard, run autonomous security assessments, triage vulnerability findings, and generate reports from one workspace. MindFort — Welcome to the Docs ## Start Here MindFort helps security and engineering teams find, prioritize, fix, and communicate security risk from one workspace. ## What MindFort Helps You Do * **Discover risk** with broad, repeatable assessments across authorized targets. * **Investigate specific questions** with Agents for focused follow-up work and retesting. * **Move findings toward resolution** with ownership, comments, tickets, patch pull requests, and validation. * **Track and communicate progress** with Coverage, Analytics, and stakeholder-ready reports. Complete organization setup, DNS verification, and first-run readiness. Go from first login to your first completed assessment. Configure targets, credentials, and login instructions. ## Core Workflow 1. Onboard and verify target ownership. 2. Add credentials and login instructions when authenticated coverage is needed. 3. Run and schedule assessments. 4. Triage and assign findings. 5. Remediate, retest, and confirm results. 6. Track coverage and trends, then generate reports. ## Documentation Map ### Getting Started * [Quick Start](/quickstart) * [Onboarding & Setup](/guides/onboarding-setup) * [Platform Overview](/guides/platform-overview) ### Core Workflows * [Overview Dashboard](/guides/dashboard) * [Analytics](/guides/analytics) * [Targets](/guides/targets) * [Scope and Guardrails](/guides/scope-and-guardrails) * [Authentication & Credentials](/guides/authentication-credentials) * [Writing Login Instructions](/guides/login-instructions) * [Assessments](/guides/assessments) * [Findings](/guides/findings) * [Coverage](/guides/coverage) * [Reporting](/guides/reporting) * [Filesystem](/guides/knowledge-lakes) * [Security Reviewer](/guides/security-reviewer) * [Target discovery](/guides/discovery) * [Patching](/guides/patching) ### Advanced Features * [Agents](/guides/tasks) * [Dual Credentials](/guides/dual-credentials) * [Settings and Billing](/guides/settings-and-billing) * [WAF Whitelisting](/guides/waf-whitelisting) * [Test Targets for Evaluation](/guides/test-targets) ### MCP Server * [Overview](/guides/mcp) ### Integrations * [Overview](/guides/integrations) * [Linear](/guides/integrations-linear) * [Jira](/guides/integrations-jira) * [Slack](/guides/integrations-slack) ### Support * [Troubleshooting](/support/troubleshooting) * [FAQ](/support/faq) ## Support * Email: [support@mindfort.ai](mailto:support@mindfort.ai) * Status: [status.mindfort.ai](https://status.mindfort.ai/) * In-app support chat # Quick Start Source: https://docs.mindfort.ai/quickstart Learn how to go from first login to a completed security assessment — set up a target, add credentials, run an assessment, and triage findings. ## Prerequisites * Access to your MindFort organization * A web application or API target you are authorized to test * Domain control for Web Application and API target verification ## Fast Path Finish organization setup and verify your first domain. In **Target Inventory**, choose the target type and add the required name, address, and description. Store a dedicated test account and login instructions for authenticated coverage. Open **New Assessment**, select a target, choose Black-Box or White-Box when available, optionally add credentials, choose an assessment method, then start. Open **Findings**, select a target, and drill into its findings. Filter by severity and keyword to prioritize. Open **Reporting** and generate a downloadable report for stakeholders. ## After First Run Your first run establishes a repeatable workflow. Choose the next step based on the outcome you need: | Goal | Next Step | | - | - | | Refresh security testing regularly | Create a recurring assessment schedule. | | Investigate or retest something specific | Launch an [Agent](/guides/tasks). | | Close the remediation loop | Assign findings, create tickets or patch pull requests, and retest fixes. | | Find untested or blocked areas | Review [Coverage](/guides/coverage). | | Track progress across targets | Review [Analytics](/guides/analytics). | | Share results | Generate an updated report for stakeholders. | Configure notifications and integrations so the right teams can act on new findings in their existing workflows. ## Next Guides * [Onboarding & Setup](/guides/onboarding-setup) * [Targets](/guides/targets) * [Assessments](/guides/assessments) * [Findings](/guides/findings) * [Coverage](/guides/coverage) * [Agents](/guides/tasks) * [Settings and Billing](/guides/settings-and-billing) * [Integrations](/guides/integrations) ## Review and remediate * Open [Coverage](/guides/coverage) to inspect the scenarios tested in your assessment. * Keep target reference material in [Filesystem](/guides/knowledge-lakes). * After deploying a fix, [retest the finding](/guides/retesting) to record whether it still reproduces. * If enabled for your organization, connect [Security Reviewer](/guides/security-reviewer) for pull request reviews. Reporting, retesting, Agents, and integrations require an upgraded plan. See [Settings and Billing](/guides/settings-and-billing) for access details. # Frequently asked questions Source: https://docs.mindfort.ai/support/faq Answers to common MindFort questions about targets, credentials, assessments, scheduling, billing, reporting, integrations, and WAF allowlisting. Confirm that you have completed the required organization and target details in the correct organization. You can skip domain verification during onboarding and finish it later in Target Inventory; the target must be verified before an assessment can start. A target is a web application, API, or available network address that you authorize MindFort to assess. Not always, but credentials are recommended when important areas are behind login. Yes. Create schedules directly from the New Assessment modal. Choose one-time, daily, weekly, bi-weekly, or monthly frequency. You can review or delete schedules from the Assessments page. Yes. Open Assessments, select the run, and cancel. Use Reporting to generate and download reports. Settings → Billing (admin access required). Billing is also accessible directly from the sidebar. Open Settings → Integrations. Permission to manage integrations and an upgraded plan are required to connect integrations. Once connected, you can create linked issues from findings, request patches, or launch Agents from Slack. Balanced is designed for frequent testing, while Deep and Ultra allow more time for investigation. Coverage and run times depend on the target, available access, and execution conditions. The assessment form shows the current credit cost and estimated duration for each method. The public API values `balanced`, `deep`, and `ultra` map to these dashboard labels. Use Agents to save templates, then create schedules from those templates. Access can depend on role, subscription plan, and payment status. Settings → WAF Configuration. Assessments aim to limit disruptive actions, but testing can generate traffic or affect application state. The impact varies with the target and assessment scope. For sensitive targets, use a non-production environment and configure low-impact testing guidance before running an assessment. Contact support if you need help. Settings → Status or [status.mindfort.ai](https://status.mindfort.ai/). ## Where do I upload reference documents? Open **Filesystem**, select the target, and upload files to its `knowledge-lake` folder. Agent-generated context is available as read-only material. See [Filesystem](/guides/knowledge-lakes). ## Does Covered mean a target has no vulnerabilities? No. It means the check's latest run completed without an active linked finding. Review the scenarios tested, incomplete checks, and current findings before drawing conclusions about the target. See [Coverage](/guides/coverage). ## Why is Security Reviewer missing? Security Reviewer is in beta and appears only when enabled for your organization. Its GitHub integration also needs repository access. See [Security Reviewer](/guides/security-reviewer). # Troubleshooting Source: https://docs.mindfort.ai/support/troubleshooting Learn how to resolve common MindFort issues — stuck onboarding, domain verification, credential failures, stalled assessments, and report downloads. ## Onboarding Does Not Complete If you cannot finish onboarding: 1. Confirm all required organization and target fields are complete. 2. If you are verifying now, re-check the DNS record and retry after propagation. 3. If you plan to verify later, choose **Skip for now** and finish onboarding. ## Target Not Available for Assessment 1. Confirm target exists in **Target Inventory**. 2. Confirm the target's verification is complete. 3. Refresh and reopen assessment modal. ## Credentials Not Working 1. Re-test credentials manually. 2. Update stored credential values. 3. Confirm login instructions match current login flow. 4. Use **Verify** in the target's **Stored Credentials** to check authentication. If a finding retest failed because of credentials, open the finding and select **Choose another credential**, then select **Retest**. For a two-account finding, choose two different accounts. See [retest credential recovery](/guides/retesting#recover-from-an-authentication-failure). ## Assessment Delays or Stalls 1. Refresh **Assessments**. 2. Check whether the run is queued behind another assessment for the same target. Queued runs start automatically. 3. Reconfirm WAF/firewall allowlisting and target access if an active run reports a problem. 4. Cancel and restart only when a new run is needed after correcting the problem. ## Missing Access to a Feature Check: * organization role permissions * plan eligibility * billing/payment status ## Report Download Fails 1. Retry from **Reporting**. 2. Check browser download and popup settings. 3. Retry in another browser session. ## API or MCP Finding Counts Differ from the Dashboard The dashboard and API use the same data but different default filters. 1. Set `exclude_secured=true` on `GET /v1/findings` or MCP `list_findings` to match the default **Open** tab (hides informational secured probes). 2. Pass `assessment_id` when comparing counts for a single assessment run. 3. Use `status=ARCHIVED` or `status=RESOLVED` for those tabs; the API defaults to `ACTIVE` only. 4. Paginate using `total` — the default `limit` is 25. See [Findings API](/api-reference/findings) for the full parameter list. ## Still Need Help * In-app support chat * [support@mindfort.ai](mailto:support@mindfort.ai) * [status.mindfort.ai](https://status.mindfort.ai/) ## An agent or integration action requires an upgrade Check the organization's plan and payment state in **Settings > Billing**. Agents, reporting, retesting, and connecting integrations require an upgraded plan. An API key or MCP connection uses the same product access checks. Also confirm your role allows the action. ## Coverage has incomplete checks Open the check and read its latest summary. Correct any identified target-access or setup problem, then run another assessment for updated coverage. Coverage checks are read-only; there is no individual rerun control.