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

# Findings

> Query repository, Hotlist, cloud security, anti-pattern, and pentest findings from the CodeAnt AI CLI

Use `codeant findings` to retrieve the findings available in the CodeAnt AI app as structured CLI output. The commands use the same authenticated organization, authorization rules, repository access, cloud scope, and pentest entitlements as the app.

<Note>
  Findings commands require a CLI version that includes `codeant findings`. Verify with `codeant findings --help` after installing or upgrading `codeant-cli`.
</Note>

## Quick start

<Steps>
  <Step title="Authenticate">
    ```bash theme={"system"}
    codeant login
    ```

    If you authenticated before application API support was added, run `codeant logout` and `codeant login` once to create a key with the required identity metadata.
  </Step>

  <Step title="List your organization connections">
    ```bash theme={"system"}
    codeant scans orgs
    ```

    When more than one connection is available, pass its exact `organizationName` and `service` using `--org` and `--service`.
  </Step>

  <Step title="Query findings">
    ```bash theme={"system"}
    codeant findings list --severity critical,high
    ```

    The command returns JSON by default, making it suitable for terminals, scripts, CI pipelines, and agents.
  </Step>
</Steps>

## Finding coverage

| Data                                                        | Command                           | Scope                                 |
| ----------------------------------------------------------- | --------------------------------- | ------------------------------------- |
| Repository list                                             | `codeant findings repos`          | Organization                          |
| SAST, SCA, IaC, Secrets, and SBOM                           | `codeant findings repo`           | Repository and scan                   |
| Anti-patterns, dead code, docstrings, and complex functions | `codeant findings repo`           | Repository and scan                   |
| Prioritized security findings                               | `codeant findings list` and `get` | Organization Hotlist                  |
| Aggregated anti-patterns                                    | `codeant findings antipatterns`   | Selected repositories or organization |
| CSPM, VM, and container findings                            | `codeant findings cloud`          | Organization and cloud scan           |
| Pentest issues and reports                                  | `codeant findings pentest`        | Organization and engagement           |

The existing `codeant scans repos`, `codeant scans results`, and `codeant hotlist list/get` commands remain supported. The unified findings namespace provides a discoverable entry point without requiring existing scripts to migrate.

## Select an organization connection

Application-backed findings commands accept these options:

| Option                      | Description                                                        |
| --------------------------- | ------------------------------------------------------------------ |
| `--org <org>`               | Organization name. Auto-selected when only one connection matches. |
| `--service <service>`       | `github`, `gitlab`, `bitbucket`, or `azuredevops`.                 |
| `--provider-base-url <url>` | Override the authenticated provider URL for a self-hosted SCM.     |

The organization, service, and provider URL must match an authenticated connection. The CLI will not send its bearer token to an arbitrary host.

## Repository discovery

List the repositories available for repo-level findings:

```bash theme={"system"}
codeant findings repos
codeant findings repos --org CodeAnt-AI
```

Use the returned `full_name`, such as `CodeAnt-AI/example`, with `findings repo`.

## Repository findings

Fetch all supported findings from the latest available scan:

```bash theme={"system"}
codeant findings repo --repo CodeAnt-AI/example --types all
```

Select a branch, scan, categories, and severities:

```bash theme={"system"}
codeant findings repo \
  --repo CodeAnt-AI/example \
  --branch main \
  --types sast,sca,iac,anti_patterns \
  --severity critical,high
```

### Repository finding types

| Type                | Data returned                        |
| ------------------- | ------------------------------------ |
| `sast`              | Static application security findings |
| `sca`               | Vulnerable dependency findings       |
| `secrets`           | Detected secrets                     |
| `iac`               | Infrastructure-as-Code findings      |
| `sbom`              | Software bill of materials data      |
| `anti_patterns`     | Code anti-pattern findings           |
| `dead_code`         | Dead-code findings                   |
| `docstring`         | Missing or incomplete docstrings     |
| `complex_functions` | Complex-function findings            |
| `all`               | Every supported type                 |

### Repository options

| Option                 | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--repo <owner/repo>`  | Repository to query. Required.                  |
| `--scan <sha>`         | Use a specific commit SHA.                      |
| `--branch <name>`      | Resolve the latest scan on a branch.            |
| `--types <list>`       | Comma-separated finding types. Default: `all`.  |
| `--severity <list>`    | Comma-separated severity filter.                |
| `--path <glob>`        | Filter by file path glob.                       |
| `--check <regex>`      | Filter by check ID or name.                     |
| `--filter-dismissed`   | Exclude dismissed findings.                     |
| `--no-false-positives` | Exclude findings classified as false positives. |
| `--limit <n>`          | Maximum findings in the page. Default: `100`.   |
| `--offset <n>`         | Pagination offset. Default: `0`.                |
| `--fields <list>`      | Return only selected finding fields.            |
| `--format <format>`    | `json`, `sarif`, `csv`, `md`, or `table`.       |
| `--output <path>`      | Write output to a file instead of stdout.       |

Export a scan as SARIF:

```bash theme={"system"}
codeant findings repo \
  --repo CodeAnt-AI/example \
  --scan 0123456789abcdef \
  --types sast,secrets \
  --format sarif \
  --output codeant.sarif
```

## Organization Hotlist

`findings list` uses the same prioritized organization snapshot, filters, stable finding IDs, and cursor pagination as the Hotlist in the app.

```bash theme={"system"}
# Critical and high findings
codeant findings list \
  --org CodeAnt-AI \
  --service github \
  --severity critical,high

# Every matching SCA and IaC finding
codeant findings list --type SCA,IaC --all

# Findings for one repository or cloud account
codeant findings list --location CodeAnt-AI/example
```

### Hotlist filters

| Option                     | Description                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| `--search <text>`          | Search titles, repositories, paths, packages, CVEs, or check IDs.        |
| `--type <values>`          | `SAST`, `SCA`, `Secrets`, `IaC`, `Infrastructure`, or `AI Exploitation`. |
| `--location <values>`      | Comma-separated repository names or cloud accounts.                      |
| `--severity <values>`      | `critical`, `high`, `medium`, `low`, or `unknown`.                       |
| `--ticket-status <values>` | `created` or `not_created`.                                              |
| `--compliance <values>`    | Compliance framework keys, such as `soc2`.                               |
| `--validation <values>`    | Validation flags, such as `exploit_confirmed`.                           |
| `--limit <n>`              | Page size from 1 to 100. Default: `30`.                                  |
| `--cursor <cursor>`        | Continue from a previous `next_cursor`.                                  |
| `--all`                    | Follow every cursor and return all matching findings.                    |
| `--max-wait <seconds>`     | Wait for the initial Hotlist snapshot. Default: `60`.                    |

Fetch one complete finding using the stable 32-character ID returned by `findings list` or shown in the app:

```bash theme={"system"}
codeant findings get 0123456789abcdef0123456789abcdef \
  --org CodeAnt-AI \
  --service github
```

## Organization anti-patterns

Query anti-patterns across every repository in the selected organization:

```bash theme={"system"}
codeant findings antipatterns --org CodeAnt-AI --service github
```

Limit the request to selected repositories:

```bash theme={"system"}
codeant findings antipatterns \
  --org CodeAnt-AI \
  --service github \
  --repos CodeAnt-AI/api,CodeAnt-AI/web
```

When `--repos` is omitted, the CLI discovers the organization's repositories before calling the aggregate anti-pattern endpoint.

## Cloud security findings

Cloud Security findings are organization and cloud-resource scoped, not repository or branch scoped. The CLI supports AWS, Azure, and GCP across three finding kinds:

| Kind                              | `--kind` value | Examples                                     |
| --------------------------------- | -------------- | -------------------------------------------- |
| Cloud Security Posture Management | `cspm`         | Misconfigurations and compliance checks      |
| VM scanning                       | `vm`           | Vulnerabilities detected on virtual machines |
| Container scanning                | `container`    | Container image vulnerabilities              |

### Discover cloud scans

```bash theme={"system"}
# CSPM history across all providers
codeant findings cloud history --provider all

# Latest CSPM scan per provider
codeant findings cloud history --provider all --latest

# VM or container scan history
codeant findings cloud history --provider all --kind vm
codeant findings cloud history --provider all --kind container
```

If one provider is unavailable, an `all` history request returns the other providers and includes an error for the unavailable provider.

### List CSPM findings

AWS can optionally be narrowed to an account:

```bash theme={"system"}
codeant findings cloud list \
  --provider aws \
  --scan-id <scan-id> \
  --account-id <aws-account-id>
```

Azure CSPM requires the tenant ID, and GCP CSPM requires the project ID:

```bash theme={"system"}
codeant findings cloud list \
  --provider azure \
  --tenant-id <tenant-id> \
  --scan-id <scan-id> \
  --severity high \
  --subscription-id <subscription-id>

codeant findings cloud list \
  --provider gcp \
  --project-id <project-id> \
  --scan-id <scan-id> \
  --framework cis
```

CSPM list filters include `--cloud-service`, `--severity`, `--status`, `--framework`, and `--min-days-unused`. AWS also supports `--exploit-attempted-only`; Azure also supports `--subscription-id`.

### List VM and container findings

VM and container scans are identified by provider, kind, and scan ID:

```bash theme={"system"}
codeant findings cloud list --provider aws --kind vm --scan-id <scan-id>
codeant findings cloud list --provider gcp --kind container --scan-id <scan-id>
```

### Get cloud finding detail

Use a finding `uid` from the list response:

```bash theme={"system"}
codeant findings cloud get \
  --provider aws \
  --kind cspm \
  --scan-id <scan-id> \
  --uid <finding-uid> \
  --cloud-service iam

codeant findings cloud get \
  --provider azure \
  --kind container \
  --scan-id <scan-id> \
  --uid <finding-uid>
```

## Pentest findings

Start by listing pentest engagements to discover their report IDs:

```bash theme={"system"}
codeant findings pentest history --org CodeAnt-AI --service github
```

Fetch all available open issues or the complete customer report:

```bash theme={"system"}
codeant findings pentest issues --report-id <report-id>
codeant findings pentest report --report-id <report-id>
```

Use the test-environment variant when an engagement includes a test run:

```bash theme={"system"}
codeant findings pentest issues --report-id <report-id> --variant test
codeant findings pentest report --report-id <report-id> --variant test
```

`--variant prod` is the default. Pentest access and critical/high finding redaction are enforced by the backend exactly as they are in the app. CLI access does not unlock restricted report content.

## Use findings with agents

The native CodeAnt MCP server exposes repository, Hotlist, anti-pattern, cloud, and pentest findings as read-only tools. See [MCP Server](/cli/mcp-server) for setup and the complete tool list.

Typical agent flow:

1. Discover the organization and scope with `codeant_scans_orgs`, `codeant_scans_repos`, `codeant_cloud_scan_history`, or `codeant_pentest_history`.
2. List and filter findings.
3. Retrieve one detailed Hotlist or cloud finding, or a pentest report.

## Troubleshooting

| Error                                 | Resolution                                                                               |
| ------------------------------------- | ---------------------------------------------------------------------------------------- |
| No authenticated organization matches | Run `codeant scans orgs`, then pass the exact `--org` and `--service`.                   |
| More than one organization matches    | Pass both `--org` and `--service`.                                                       |
| Access denied (403)                   | Run `codeant logout`, then `codeant login`.                                              |
| Hotlist is still building             | Retry or increase `--max-wait`.                                                          |
| Azure or GCP CSPM scope is missing    | Pass `--tenant-id` for Azure or `--project-id` for GCP.                                  |
| Scan or report not found              | Use the corresponding history command and verify the selected provider and organization. |
| Pentest fields are redacted           | Unlock the engagement in the app; the CLI follows the same entitlement.                  |

<CardGroup cols={3}>
  <Card title="Scan Center" icon="magnifying-glass-chart" href="/cli/scan-center">
    Explore the existing `scans` commands and scan metadata.
  </Card>

  <Card title="Cloud Security" icon="cloud" href="/cloud_security/cspm">
    Learn about CSPM, VM scanning, and container scanning.
  </Card>

  <Card title="Pentesting" icon="shield-halved" href="/pentesting/overview">
    Learn how pentest engagements and reports work in the app.
  </Card>
</CardGroup>