Metadata-Version: 2.4
Name: pandoraspec
Version: 0.2.0
Summary: DORA Compliance Auditor for OpenAPI Specs
Author-email: Ulises Merlan <ulimerlan@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: schemathesis==4.9.1
Requires-Dist: typer[all]
Requires-Dist: rich
Requires-Dist: weasyprint
Requires-Dist: jinja2
Requires-Dist: requests

# PanDoraSpec

**The Open DORA Compliance Engine for OpenAPI Specs.**

PanDoraSpec is a CLI tool that performs deep technical due diligence on APIs to verify compliance with **DORA (Digital Operational Resilience Act)** requirements. It compares OpenAPI/Swagger specifications against real-world implementation to detect schema drift, resilience gaps, and security issues.

---

## 📦 Installation

```bash
pip install pandoraspec
```

### System Requirements
The PDF report generation requires `weasyprint`, which depends on **Pango**.

**macOS:**
```bash
brew install pango
```

**Debian / Ubuntu:**
```bash
sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0
```

## 🛠️ Development Setup

To run the CLI locally without reinstalling after every change:

1. **Clone & CD**:
```bash
git clone ...
cd pandoraspec
```

2. **Create & Activate Virtual Environment**:
It's recommended to use a virtual environment to keep dependencies isolated.
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. **Editable Install**:
```bash
pip install -e .
```
This links the `pandoraspec` command directly to your source code. Any changes you make will be reflected immediately.

## 🚀 Usage

Run the audit directly from your terminal.

### Basic Scan
```bash
pandoraspec https://petstore.swagger.io/v2/swagger.json
```

### With Options
```bash
pandoraspec https://api.example.com/spec.json --vendor "Stripe" --key "sk_live_..."
```

### Local File
```bash
pandoraspec ./openapi.yaml
```

---

## 🏎️ Zero-Config Testing (DORA Compliance)

For standard **DORA compliance**, you simply need to verify that your API implementation matches its specification. **No configuration is required.**

```bash
pandoraspec https://petstore.swagger.io/v2/swagger.json
```

This runs a **fuzzing** audit where random data is generated based on your schema types (e.g., sending random integers for IDs). 
- **Value:** This is sufficient to prove that your API correctly handles unexpected inputs and adheres to the basic contract (e.g., returning 400 Bad Request instead of 500 Server Error).
- **Limitation:** Detailed business logic requiring valid IDs (e.g., `GET /user/{id}` where `{id}` must exist) may return `404 Not Found`. This is acceptable for a compliance scan but may not fully exercise deeper code paths.

---

## 🧠 Advanced Testing with Seed Data

To test **specific business workflows** (e.g., successfully retrieving a user profile), you can provide "Seed Data". This tells PanDoraSpec to use known, valid values instead of random fuzzing data.

```bash
pandoraspec https://petstore.swagger.io/v2/swagger.json --config seed_parameters.yaml
```

### Configuration Hierarchy
You can define seed values at three levels of specificity. The engine resolves values in this order: **Endpoints > Verbs > General**.

```yaml
seed_data:
  # 1. General: Applies to EVERYTHING (path params, query params, headers)
  general:
    username: "test_user"
    limit: 50

  # 2. Verbs: Applies only to specific HTTP methods (Overwrites General)
  verbs:
    POST:
      username: "admin_user" # Creation requests use a different user

  # 3. Endpoints: Applies only to specific routes (Overwrites Everything)
  endpoints:
    /users/me:
      GET:
        limit: 10
```

### 🔗 Dynamic Seed Data (Chaining Requests)
You can even test **dependency chains** where one endpoint requires data from another (e.g., get a User ID from a search result to query their profile).

**Supported Features:**
- **Dynamic Resolution:** Fetch a value from another API call before running the test.
- **Extraction:** Extract values from JSON responses or plain text.
- **Parameter Interpolation:** Use `{param}` in the dependency URL to chain multiple steps.

```yaml
endpoints:
  /user/{username}:
    GET:
      username:
        # 1. Fetch the user list first
        # 2. Extract the 'username' field from the response
        from_endpoint: "GET /users/search?role=admin"
        extract: "data.items.0.username"

  /orders/{orderId}:
    GET:
      orderId:
        # 1. Use the {userId} from our general seeds
        # 2. Call /users/{userId}/latest-order
        # 3. Extract the ID using Regex from a message string
        from_endpoint: "GET /users/{userId}/latest-order"
        extract: "message"
        regex: "Order ID: ([0-9]+)"
```

---

## 🛡️ What It Checks

### Module A: The Integrity Test (Drift)
Checks if your API implementation matches your documentation.
- **Why?** DORA requires you to monitor if the service effectively supports your critical functions. If the API behaves differently than documented, it's a risk.

### Module B: The Resilience Test
Stress tests the API to ensure it handles invalid inputs gracefully (`4xx` vs `5xx`).
- **Why?** DORA Article 25 calls for "Digital operational resilience testing".

### Module C: Security Hygiene
Checks for common security headers and configurations.

### Module D: The Report
Generates a PDF report: **"DORA ICT Third-Party Technical Risk Assessment"**.

---

## 📄 License

MIT
