Metadata-Version: 2.4
Name: context-confidence-rating
Version: 0.1.4
Summary: Calculate context-aware confidence scores for security findings
Home-page: https://github.com/secuardenai/context-confidence-rating
Author: Secuarden Team
Author-email: Secuarden Team <hello@secuarden.com>
License: MIT
Project-URL: Homepage, https://github.com/secuardenai/context-confidence-rating
Project-URL: Documentation, https://github.com/secuardenai/context-confidence-rating#readme
Project-URL: Repository, https://github.com/secuardenai/context-confidence-rating
Project-URL: Bug Reports, https://github.com/secuardenai/context-confidence-rating/issues
Keywords: security,vulnerability,context,confidence,sast,analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Context Confidence Rating (CCR)

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
![PyPI](https://img.shields.io/pypi/v/context-confidence-rating)
![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)
![Status](https://img.shields.io/badge/status-beta-orange)

CCR generates lightweight repository context for LLM-assisted security review.

It scans a codebase for useful review signals such as frameworks, dependencies,
entry points, configuration files, tests, and security controls. The output can
be pasted into an LLM prompt or used by reviewers to understand what context is
available before triaging scanner findings.

CCR is a context completeness score. It does not prove whether a vulnerability
is exploitable, and it does not replace CVSS, SAST, or manual security review.

Built by [Secuarden](https://secuarden.com).

## Quick Start

```bash
pip install context-confidence-rating

# Score the repository's available review context
ccr /path/to/repo

# Generate LLM-ready context
ccr context /path/to/repo

# Generate file-specific context
ccr context /path/to/repo --file src/api/auth.py
```

## What CCR Gives You

- A 0-100 context completeness score
- Repository architecture signals
- Entrypoints and route-like files
- Dependency and lockfile information
- Security controls such as `SECURITY.md`, `CODEOWNERS`, and CI checks
- File-specific hints for user input, database operations, auth checks, and validation
- Markdown, JSON, and XML output for LLM workflows

## Python API

```python
from ccr import ContextAnalyzer, ContextGenerator

analyzer = ContextAnalyzer("/path/to/repo")
baseline = analyzer.calculate_repo_baseline_ccr()
print(f"Repository context score: {baseline.score}/100")

finding_context = analyzer.calculate_ccr({
    "file": "api/payments.py",
    "vulnerability": "SQL Injection",
    "severity": "HIGH",
})
print(finding_context.to_dict())

generator = ContextGenerator("/path/to/repo")
context = generator.generate_context(target_file="src/api/auth.py")
print(generator.to_markdown(context))
```

## CLI Usage

```bash
# Human-readable score
ccr /path/to/repo

# Verbose reasoning
ccr /path/to/repo --verbose

# JSON score output
ccr /path/to/repo --json

# Include a scanner finding for context scoring
ccr /path/to/repo \
  --file "src/auth.py" \
  --vuln "Hardcoded Credentials" \
  --severity "CRITICAL"
```

## LLM Context Generation

```bash
# Markdown, default
ccr context /path/to/repo

# JSON
ccr context /path/to/repo --format json

# XML
ccr context /path/to/repo --format xml

# Focus on one file
ccr context /path/to/repo --file src/api/auth.py
```

Example prompt:

```text
Here is repository context generated by CCR:

<repo_context>
{paste CCR output}
</repo_context>

Here is a scanner finding:

<finding>
SQL Injection in api/users.py line 42
</finding>

Use the context to identify what should be manually checked before triage.
```

## Score Meaning

| Score | Label | Meaning |
| --- | --- | --- |
| 71-100 | High | Strong repository signals are available for review |
| 41-70 | Medium | Some useful context exists, but reviewers should expect gaps |
| 0-40 | Low | Limited context was detected; manual review needs more care |

## Signals

| Signal | Weight | What It Means |
| --- | ---: | --- |
| Framework Detection | 15 | Framework or platform clues were found |
| Dependency Tracking | 15 | Dependency files or lockfiles were found |
| Dataflow Readiness | 20 | Imports, functions, and classes suggest code is structured enough to inspect |
| Entry Point Mapping | 15 | Route, API, or main entry files were found |
| Config Awareness | 10 | Configuration files were found |
| Security Controls | 15 | Security process files or scanner configs were found |
| Test Coverage | 10 | Test directories or test files were found |

## Installation

From PyPI:

```bash
pip install context-confidence-rating
```

From source:

```bash
git clone https://github.com/secuardenai/context-confidence-rating.git
cd context-confidence-rating
pip install -e ".[dev]"
pytest
```

## CI Example

```yaml
name: CCR Context Check

on: [pull_request]

jobs:
  ccr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install context-confidence-rating
      - run: ccr . --json > ccr-report.json
      - run: ccr context . --format markdown > repo-context.md
```

## Development

```bash
pip install -e ".[dev]"
pytest
black ccr/ tests/ examples/
flake8 ccr/ tests/ examples/ --count --select=E9,F63,F7,F82 --show-source --statistics
```

## Project Status

CCR is beta software. The current implementation is intentionally lightweight
and heuristic-based. Contributions that improve precision, fixtures, language
coverage, and documentation are welcome.

## Security

Please report security issues privately. See [SECURITY.md](SECURITY.md).

## License

MIT License. See [LICENSE](LICENSE).
