# 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

### 🛡️ OWASP Top 10 Security Rules

Advanced detection for Python API applications:

- **AP009** - Broken Authentication (Critical) — write endpoints without auth, authentication via GET, credential handling issues
- **AP010** - Injection Vulnerabilities (High) — path traversal, SQL injection, command injection, template injection, open redirects
- **AP011** - Broken Access Control (Critical) — IDOR vulnerabilities, missing authorization on admin endpoints, privilege escalation
- **AP012** - Security Misconfiguration (High) — debug endpoints, config exposure, unprotected admin operations, file upload issues
- **AP013** - Vulnerable Components (High) — deprecated auth methods, XXE, unsafe deserialization, JSONP, insecure random

### 🔑 Secrets Detection

- **AP014** - Hardcoded Secrets (Critical) — detects 15+ secret patterns in source files
- AWS, GitHub, Slack, Stripe, Google, Twilio, SendGrid tokens
- Database connection strings with credentials
- Private keys and JWT secrets
- Passwords and API keys
- **AP015** - API Key Exposure (High) — keys in URL parameters, authentication via GET, insecure credential handling

### 📂 Dependency Scanning

- **AP016** - Insecure Dependencies (High) — scans requirements.txt, Pipfile, and pyproject.toml for vulnerable packages

### 📊 Diff Mode

Compare scans over time to track security improvements or regressions:

```bash
apiposture-pro diff baseline.json current.json
```

### 📈 Historical Tracking

Automatic scan history with SQLite storage:

```bash
apiposture-pro history list
apiposture-pro history trend -p /path/to/project
```

### 🎯 Risk Scoring

Automated risk assessment (0-100 scale) based on:
- Findings severity (50% weight)
- Public endpoint exposure (30% weight)
- Attack surface area (20% weight)

Risk levels: CRITICAL (75+), HIGH (50-74), MEDIUM (25-49), LOW (1-24), MINIMAL (0)

## Installation

### For Pro Users (Recommended)

Install the standalone Pro tool - includes everything:

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

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

# Verify activation
apiposture-pro status
```

**That's it!** Pro tool is fully standalone and includes both free and Pro rules.

### For Free Users

If you only need basic rules, install the free CLI:

```bash
pip install apiposture
```

### CI/CD Alternative

Set license via environment variable (no activation needed):

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

## Usage

### Scan Your API

Use the Pro CLI for scanning (includes both free and Pro rules):

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

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

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

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

### Manage Your License

```bash
# Check license status
apiposture-pro status

# Deactivate license
apiposture-pro deactivate
```

### Example Output

```bash
$ apiposture-pro scan .

Scanning: /home/user/my-api
Loading Pro rules...

Scan Complete
  Endpoints found: 25
  Findings: 8

Findings by Severity:
  CRITICAL: 2
  HIGH: 3
  MEDIUM: 2
  LOW: 1

Risk Score:
  52/100 (HIGH)
  Findings: 35/50
  Exposure: 12/30
  Surface Area: 5/20
```

### Automatic History Tracking

Every scan with `--with-history` is saved to your local history database (`~/.apiposture/history.db`):

```bash
$ apiposture-pro scan /path/to/api --with-history
[scan output...]
✓ Saved as scan #42

# View your scan history
$ apiposture-pro history list

# Show trend for your project
$ apiposture-pro history trend -p /path/to/api
```

### Compare Scans (Diff Mode)

Track security improvements over time:

```bash
# Save baseline
apiposture-pro scan /path/to/api -f baseline.json

# Make security improvements...

# Scan again
apiposture-pro scan /path/to/api -f current.json

# Compare results
apiposture-pro diff baseline.json current.json
```

### View History

Pro records scan history:

```bash
# List recent scans
apiposture-pro history list

# View trends over time
apiposture-pro history trend -p /path/to/api

# Show specific scan
apiposture-pro history show <scan-id>

# Clean old scans (90+ days)
apiposture-pro history cleanup --days 90
```

## CI/CD Integration

Use ApiPosture Pro in your CI/CD pipeline:

### GitHub Actions

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install ApiPosture Pro
        run: pip install apiposture-pro

      - name: Run security scan
        run: apiposture-pro scan . --output json --file results.json
        env:
          APIPOSTURE_LICENSE_KEY: ${{ secrets.APIPOSTURE_LICENSE_KEY }}

      - name: Upload results
        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
    displayName: 'Install ApiPosture Pro'

  - script: apiposture-pro scan . --output json --file $(Build.ArtifactStagingDirectory)/results.json
    displayName: 'Security Scan'
    env:
      APIPOSTURE_LICENSE_KEY: $(ApiPostureLicenseKey)
```

## Security Rules Reference

### AP009: Broken Authentication

**Severity:** Critical

Detects write operations without authentication, authentication endpoints accepting GET requests, credential handling without protection, and session management vulnerabilities.

**Recommendation:** Require authentication for write operations. Use POST for authentication. Protect credential-handling endpoints.

### AP010: Injection Vulnerabilities

**Severity:** High

Detects path traversal in file parameters, SQL injection patterns, command injection risks, template injection, and open redirect vulnerabilities.

**Recommendation:** Use parameterized queries. Validate and sanitize file paths. Avoid executing user input. Use allowlists for redirects.

### AP011: Broken Access Control

**Severity:** Critical

Detects IDOR vulnerabilities, administrative endpoints without role checks, bulk operations without authorization, and privilege escalation risks.

**Recommendation:** Implement ownership validation. Require roles for admin endpoints. Check permissions on bulk operations.

### AP012: Security Misconfiguration

**Severity:** High

Detects debug endpoints, configuration exposure, unprotected administrative operations, and file upload without restrictions.

**Recommendation:** Remove debug endpoints from production. Protect configuration endpoints. Require authentication for admin operations.

### AP013: Vulnerable Components

**Severity:** High

Detects deprecated authentication methods (MD5, SHA1, Basic Auth), XXE vulnerabilities, unsafe deserialization (pickle), JSONP endpoints, and insecure random number generation.

**Recommendation:** Use bcrypt/Argon2 for passwords. Disable XML external entities. Use JSON instead of pickle. Replace JSONP with CORS. Use secrets module for cryptographic randomness.

### AP014: Hardcoded Secrets

**Severity:** Critical

Detects hardcoded secrets in source code including AWS keys, API tokens, passwords, database credentials, and private keys.

**Recommendation:** Never hardcode secrets. Use environment variables or secret management services (AWS Secrets Manager, HashiCorp Vault). Rotate exposed credentials immediately.

### AP015: API Key Exposure

**Severity:** High

Detects API keys in URL parameters, authentication via GET requests, and credentials passed via insecure methods.

**Recommendation:** Pass API keys in HTTP headers (Authorization: Bearer). Use POST for authentication. Never put credentials in URLs.

### AP016: Insecure Dependencies

**Severity:** High

Scans requirements.txt, Pipfile, and pyproject.toml for packages with known vulnerabilities.

**Recommendation:** Keep dependencies updated. Run regular security audits. Review dependency changes before deployment.

## Supported Frameworks

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

## Privacy & Security

🔒 **Your code stays on your machine**

- All analysis is performed **100% locally**
- No code, findings, or project data is uploaded to external servers
- No telemetry or usage tracking
- SQLite history database is stored locally on your machine (`~/.apiposture/history.db`)

## License Tiers

### Pro License
- OWASP Top 10 rules (AP009-AP013)
- Secrets detection (AP014-AP015)
- Dependency scanning (AP016)
- Diff mode
- Historical tracking
- Risk scoring
- Standard support

### Enterprise License
- All Pro features
- Priority support
- Custom rule development
- Site licenses available

## 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.0.0 (2026-02-09)
- Initial release
- OWASP Top 10 security rules (AP009-AP013)
- Secrets detection (AP014-AP015)
- Dependency scanning (AP016)
- Diff mode for comparing scans
- Historical tracking with SQLite
- Risk scoring analysis (0-100 scale)
- License management with JWT validation
- Extension deployment capability
- Python 3.10, 3.11, 3.12 support

---

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