> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Review and triage security findings

> Filter Tolmo and third-party findings, import scanner reports, create drafts, and record status decisions with the Tolmo CLI.

Use `tolmo findings` to review Tolmo-authored findings and findings from connected scanners in one list. All subcommands accept `--org` and `--profile`. Use `--json` for structured output.

## List and filter findings

```bash theme={null}
tolmo findings list
tolmo findings list --status open --severity critical
tolmo findings list --origin wiz --search payments --json
tolmo findings list --include-info --json
```

The CLI follows the API's pagination and returns all matching findings. JSON output is an array. Ordinary callers see published Tolmo findings and ingested scanner findings. Informational findings and findings without a severity are excluded unless you pass `--include-info`.

| Flag | Description |
| - | - |
| `--status` | Comma-separated statuses: `open`, `in_review`, `closed`, `acknowledged`, `false_positive` |
| `--severity` | `critical`, `high`, `medium`, `low`, or `info` |
| `--origin` | `tolmo` or a provider name, such as `wiz` |
| `--search` | Search titles, external IDs, rules, and resource keys |
| `--query` | A findings query expression |
| `--state` | Comma-separated lifecycle states |
| `--retest` | Comma-separated retest values |
| `--rule` | Exact provider rule |
| `--provider-status` | Comma-separated provider statuses |
| `--verdict` | `tolmo` or `none` |
| `--scope` | `all` (default) or `open` |
| `--include-info` | Include informational findings and findings without a severity |

Use the [filter facets endpoint](https://docs.tolmo.com/api-reference/findings/list-finding-filter-facets.md) to discover filter values for your organization.

## View a finding

```bash theme={null}
tolmo findings get <finding-id>
tolmo findings get <finding-id> --json
```

The detail view works for Tolmo-authored and scanner findings. You can use a full UUID or a unique ID prefix from the list. Use a longer prefix if the CLI reports multiple matches.

## Create a draft

API keys and ordinary user tokens can create draft findings. They cannot publish findings.

```bash theme={null}
tolmo findings create --title "Overpermissive storage access" --severity high --resource-name customer-exports --description-file ./finding.md
```

`--title` and `--severity` are required. When you use a user token, also supply `--resource-name` to identify the affected resource. The default visibility is `draft`, and the default status is `open`. Use either `--description` for inline Markdown or `--description-file` for a file. Pass `--description-file -` to read stdin.

Save the ID returned by creation. Drafts are not included in the ordinary customer findings list.

## Import a scanner report

Use `upload` to import a Markdown security report as third-party findings:

```bash theme={null}
tolmo findings upload ./security-report.md --provider code-security --source payments-review --json
```

The report must contain a `## Unified finding details` section and findings with `### USR-<number>: <title>` headings:

```markdown security-report.md theme={null}
# Security review

## Unified finding details

### USR-0001: Storage permissions need review

- **Highest reported severity:** `HIGH`

The storage policy grants broader access than this service requires.

**Recommended remediation:** Restrict the policy to the required resources.
```

The CLI parses findings locally and uploads them in batches.

| Flag | Description |
| - | - |
| `--provider` | Required producer name. Use lowercase letters, digits, `.`, `_`, or `-`; start with a letter or digit |
| `--source` | Stable import source. Defaults to the report filename; required for stdin |
| `--status` | Provider status assigned to imported findings; defaults to `open` |
| `--kind` | Finding kind; defaults to `code_security` |

Keep the provider, source, and finding identifiers stable when you import an updated report. Matching records are updated instead of duplicated.

## Change status

```bash theme={null}
tolmo findings status <finding-id> in_review --justification "The fix is under review" --proof-url https://github.com/acme/payments/pull/42
tolmo findings status <finding-id> closed --justification-file ./resolution.md
tolmo findings status <finding-id> false_positive --justification "The affected configuration is not used"
```

The supported statuses are `open`, `in_review`, `closed`, `acknowledged`, and `false_positive`. Use the underscore in `false_positive`.

You can attach a justification to `in_review`, `closed`, or `false_positive`. Use either `--justification` or `--justification-file`; `-` reads stdin. `--proof-url` is available only for `in_review` and requires an HTTP or HTTPS URL.

For scanner findings, status changes affect Tolmo's record. They do not update the source provider. A later scan can replace the local status.

## Review status history

```bash theme={null}
tolmo findings history <finding-id>
tolmo findings history <finding-id> --json
```

## Manage evidence attachments

Sign in with `tolmo auth login` to manage attachments. These operations require a user token; organization API keys are not accepted.

```bash theme={null}
tolmo findings attachments list <finding-id>
tolmo findings attachments upload <finding-id> ./evidence.pdf --title "Review evidence"
tolmo findings attachments download <finding-id> <attachment-id> --output ./evidence.pdf
tolmo findings attachments delete <finding-id> <attachment-id> --yes
```

Uploads support files up to 250 MiB. Downloads use the stored filename unless you pass `--output`. Pass `--force` to overwrite an existing local file. Attachment deletion is permanent and requires `--yes`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.