contrast-triage 0.1.6
AI-powered triage by Contrast Security, Inc.
Requires Python: <4.0.0,>=3.13.0

# Contrast Triage

An AI-powered triage system that automatically analyzes security vulnerability findings from SARIF
files to classify them as true positives or false positives. The system uses advanced AI agents
built on LangGraph to read source code, understand business logic context, and provide detailed
justifications for each classification.

## Features

- **Automated Vulnerability Analysis**: Processes SARIF (Static Analysis Results Interchange Format) files from SAST tools
- **AI-Powered Classification**: Uses LLM agents to determine if findings are true positives or false positives
- **Contextual Understanding**: Reads and analyzes source code to understand business logic around vulnerabilities
- **Detailed Justification**: Provides reasoning and confidence levels for each classification
- **Cost Tracking**: Tracks token usage and costs across multiple LLM invocations
- **Streaming Output**: Real-time progress feedback with Rich console formatting
- **Multiple Model Support**: Works with various AWS Bedrock models (Claude, Nova, Llama, etc.)

## Installation

### Quick Install (Recommended)

Install directly from PyPI using `uv` (recommended) or `pipx`:

```bash
# Using uv (recommended)
uv tool install contrast-triage

# Or using pipx
pipx install contrast-triage
```

This installs the `contrast-triage` command in an isolated environment and makes it available on your PATH.

Verify the installation:

```bash
contrast-triage --version
```

For developer setup and AWS Bedrock configuration, see [DEVELOPER.md](DEVELOPER.md).

## Usage

### Basic Command Structure

```bash
contrast-triage [OPTIONS] INPUT_SARIF OUTPUT_SARIF
```

### Required Arguments

- `INPUT_SARIF`: Path to the input SARIF file containing vulnerability findings
- `OUTPUT_SARIF`: Path where the modified SARIF file will be written

### Examples

See specific examples to run against here: [real examples](examples/README.md)

#### 1. Basic Usage

Analyze all findings in a SARIF file:

```bash
contrast-triage \
  findings.sarif \
  findings-triaged.sarif \
  --srcroot /path/to/source/code
```

#### 2. Analyze a Specific Finding

Process only finding at index 5:

```bash
contrast-triage \
  findings.sarif \
  findings-triaged.sarif \
  --index 5 \
  --srcroot ./src
```

#### 3. Dry Run (No LLM Costs)

Test the workflow without making LLM calls:

```bash
contrast-triage \
  --dry-run \
  findings.sarif \
  findings-triaged.sarif
```

#### 4. Custom Agent Logs

Specify a custom log file location:

```bash
contrast-triage \
  findings.sarif \
  findings-triaged.sarif \
  --agent-log /tmp/my_triage_run.log
```

For information about supported models and model configuration, see [DEVELOPER.md](DEVELOPER.md).

## Output Format

The tool modifies the input SARIF file by adding a `contrast.triageAnalysis` property to each analyzed finding:

```json
{
  "results": [
    {
      "ruleId": "SQL_INJECTION",
      "message": { "text": "Potential SQL injection" },
      "properties": {
        "contrast.triageAnalsysis" : {
          "classification": "FALSE_POSITIVE"
        }
      }
    }
  ]
}
```

## Cost Tracking

Token usage and costs are displayed at the end of each run:

```
Token Tracker: {
  'us.anthropic.claude-sonnet-4-5-20250929-v1:0': TokenCost(
    input_tokens=15234,
    output_tokens=2341,
    input_cost=0.0502,
    output_cost=0.0386,
    total_cost=0.0888
  )
}
```

Agent logs (JSON format) are written to `triage_agent.log` (or your specified location) for detailed debugging.

## Troubleshooting

### "No findings found in SARIF file"

Ensure your SARIF file contains at least one run with results:
```bash
# Validate SARIF structure
python -c "import json; print(json.load(open('findings.sarif'))['runs'][0]['results'])"
```

### AWS Credentials Issues

For AWS Bedrock setup and credential configuration, see [DEVELOPER.md](DEVELOPER.md).

### High Costs

To reduce LLM costs:
- Use `--dry-run` for testing
- Process specific findings with `--index` instead of all at once
- Test on a small SARIF file first

For information about different model options and their costs, see [DEVELOPER.md](DEVELOPER.md).

## Contributing

Contributions are welcome! For information about development setup, testing, code formatting, and release procedures, see [DEVELOPER.md](DEVELOPER.md).