# ApiPosture Pro

**Professional security extension for Python API security scanning**

Extends the open-source [ApiPosture CLI](https://github.com/apiposture/ApiPosture.Python) with advanced security rules, secrets detection, diff mode, historical tracking, and risk scoring.

🔒 **100% Local Analysis** - Your code never leaves your machine. All scanning is performed locally on your computer or CI/CD runner.

## Features

### Free Rules (AP001-AP008)
Included automatically — public endpoint detection, missing auth, authorization conflicts, sensitive route keywords, and more.

### Pro Rules

| ID | Name | Severity |
|----|------|----------|
| AP009 | Broken Authentication | Critical |
| AP010 | Injection Vulnerabilities | High |
| AP011 | Broken Access Control | Critical |
| AP012 | Security Misconfiguration | High |
| AP013 | Vulnerable Components | High |
| AP014 | Hardcoded Secrets (15+ patterns) | Critical |
| AP015 | API Key Exposure | High |
| AP016 | Insecure Dependencies | High |

### Additional Pro Features
- **Risk Scoring** — 0–100 scale (severity 50%, exposure 30%, surface area 20%)
- **Diff Mode** — compare baseline vs current scan
- **History Tracking** — SQLite-backed scan history with trends

## Installation

```bash
# Install Pro CLI (includes all free and Pro rules)
pip install apiposture-pro

# Activate your license
apiposture-pro activate XXXX-XXXX-XXXX-XXXX

# Verify activation
apiposture-pro status
```

### CI/CD: set license via environment variable

```bash
export APIPOSTURE_LICENSE_KEY=<your-jwt-token>
```

## Usage

### Scan

```bash
# Basic scan
apiposture-pro scan /path/to/your/api

# JSON output
apiposture-pro scan /path/to/your/api --output json --file report.json

# Save to history
apiposture-pro scan /path/to/your/api --with-history

# Disable risk score
apiposture-pro scan /path/to/your/api --no-risk-score
```

### Diff Mode

```bash
apiposture-pro scan /path/to/api -f baseline.json
# ... make changes ...
apiposture-pro scan /path/to/api -f current.json
apiposture-pro diff baseline.json current.json
```

### History

```bash
apiposture-pro history list
apiposture-pro history trend -p /path/to/api
apiposture-pro history show <scan-id>
apiposture-pro history cleanup --days 90
```

### License

```bash
apiposture-pro status
apiposture-pro deactivate
```

## Enterprise

Enterprise features require an Enterprise license (`APIPOSTURE_LICENSE_KEY` or `apiposture-pro activate`).

### Compliance Reports

Generate SOC 2 / ISO 27001 compliance reports mapped to your scan findings:

```bash
# Generate PDF + HTML report
apiposture-pro compliance report . --framework soc2 --output both

# Specific framework, operator attribution
apiposture-pro compliance report . --framework iso27001 --output pdf --operator "Acme Corp"

# All frameworks
apiposture-pro compliance report . --framework all --output both
```

### Compliance Score in Scan Output

```bash
# Show compliance score alongside risk score
apiposture-pro scan . --comp-framework soc2
apiposture-pro scan . --comp-framework iso27001
```

### Starter Kits

Emit a pre-configured policy file, sample report, and GitHub Actions workflows:

```bash
apiposture-pro compliance starter-kit soc2 ./compliance/
apiposture-pro compliance starter-kit iso27001 ./compliance/
```

Generates: `.apiposture-policy.json`, `sample-report.html`, `github-actions/apiposture-pr-gate.yml`, `github-actions/apiposture-weekly-report.yml`, `README.md`.

### Policy Enforcement

Place `.apiposture-policy.json` in your project root (generated by `starter-kit` or written manually). The scanner reads it automatically and exits with code 1 on violations:

```json
{
  "zero_tolerance": ["AP014", "AP009"],
  "warn": ["AP010", "AP011"]
}
```

### Operator Attribution

```bash
apiposture-pro scan . --operator "Security Team"
```

The operator name is embedded in findings output and scan records.

### Audit Trail Export

Export a tamper-evident audit trail from scan history:

```bash
# JSON export (stdout)
apiposture-pro history export --format json

# JSON to file
apiposture-pro history export --format json --output-file audit.json

# PDF export
apiposture-pro history export --format pdf --output-file audit-export.pdf

# Specific scan record
apiposture-pro history export --scan-id 42 --format pdf --output-file audit-42.pdf
```

### Integrity Verification

```bash
# Verify latest scan record integrity
apiposture-pro verify

# Verify specific scan
apiposture-pro verify --scan-id 42
```

## CI/CD Integration

### GitHub Actions

```yaml
name: Security Scan
on: [push, pull_request]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install apiposture-pro
      - run: apiposture-pro scan . --output json --file results.json
        env:
          APIPOSTURE_LICENSE_KEY: ${{ secrets.APIPOSTURE_LICENSE_KEY }}
      - uses: actions/upload-artifact@v4
        with:
          name: security-scan-results
          path: results.json
```

### GitLab CI

```yaml
security_scan:
  image: python:3.12
  script:
    - pip install apiposture-pro
    - apiposture-pro scan . --output json --file results.json
  variables:
    APIPOSTURE_LICENSE_KEY: $APIPOSTURE_LICENSE_KEY
  artifacts:
    paths:
      - results.json
```

### Azure DevOps

```yaml
steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.12'
  - script: pip install apiposture-pro
  - script: apiposture-pro scan . --output json --file $(Build.ArtifactStagingDirectory)/results.json
    env:
      APIPOSTURE_LICENSE_KEY: $(ApiPostureLicenseKey)
```

## Supported Frameworks

- **FastAPI** 0.100+
- **Flask** 2.3+
- **Django REST Framework** 3.14+

## Privacy

All analysis is performed **100% locally**. No code, findings, or project data is uploaded to external servers. Only the license key is sent to `api.apiposture.com` during activation/validation. SQLite history is stored at `~/.apiposture/history.db`.

## License Tiers

| Feature | Pro | Enterprise |
|---------|-----|------------|
| Free rules (AP001-AP008) | ✓ | ✓ |
| OWASP rules (AP009-AP013) | ✓ | ✓ |
| Secrets detection (AP014-AP015) | ✓ | ✓ |
| Dependency scanning (AP016) | ✓ | ✓ |
| Diff mode | ✓ | ✓ |
| Historical tracking | ✓ | ✓ |
| Risk scoring | ✓ | ✓ |
| Compliance reports (SOC 2 / ISO 27001) | — | ✓ |
| Compliance score + trend | — | ✓ |
| Starter kits | — | ✓ |
| Policy enforcement | — | ✓ |
| Audit trail export | — | ✓ |
| Operator attribution | — | ✓ |
| Integrity verification | — | ✓ |

## Links

- **Free ApiPosture CLI:** [GitHub](https://github.com/apiposture/ApiPosture.Python) | [PyPI](https://pypi.org/project/apiposture)
- **ApiPosture Pro:** [PyPI](https://pypi.org/project/apiposture-pro)
- **Documentation:** https://docs.apiposture.com
- **Support:** support@apiposture.com

## Changelog

### 1.1.0
- Enterprise tier: compliance reports (SOC 2 / ISO 27001), compliance score, starter kits, policy enforcement, audit trail export, operator attribution, integrity verification

### 1.0.0 (2026-02-09)
- Initial release: OWASP rules (AP009-AP013), secrets detection (AP014-AP015), dependency scanning (AP016), diff mode, history tracking, risk scoring

---

Copyright © 2026 ApiPosture. All rights reserved. | [License Terms](LICENSE)
