auditapi

AuditAPI

Is your API a time bomb? Audit it in 3 seconds.

AuditAPI is a high-performance CLI tool that analyzes OpenAPI (Swagger) specifications with strict quality rules, weighted scoring, and security vulnerability detection. Designed for teams who take API quality seriously.

🚀 Quick Test

# Using npx (without installing)
npx auditapi audit ./openapi.yaml

# Or using Docker
docker run --rm -v $(pwd):/app auditapi audit /app/openapi.yaml

📸 AuditAPI in Action

╔══════════════════════════════════════════════════════════╗
║                    AUDITAPI REPORT                       ║
╚══════════════════════════════════════════════════════════╝

📄 File:     /tests/casing-mixed.yaml
⏱️  Duration: 180ms
📅 Time:     2026-02-17T11:12:54.767Z

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                     FINAL GRADE: B
                     SCORE: 86/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Category Breakdown:
   ✅ security        Weight: 0.30  Penalty: 0
   ⚠️  completeness    Weight: 0.20  Penalty: 30
   ✅ structure       Weight: 0.15  Penalty: 0
   ⚠️  consistency     Weight: 0.10  Penalty: 35
   ⚠️  architecture    Weight: 0.25  Penalty: 20

📊 Summary:
   Total Violations: 10
   ❌ Errors:         2
   ⚠️  Warnings:       8

✅ PASSED


Detailed Violations:
──────────────────────────────────────────────────────────

❌ [cns-mixed-styles] ERROR
   CNS-01: Mixed property casing detected
   Path: components.schemas
   Line: 37:10

🎯 Why Do We Fail?

AuditAPI detects critical problems in 5 categories:

Category	Weight	Common Issues	Impact
🔒 Security	30%	OWASP API Top 10, HTTPS not enforced, weak authentication, mass assignment	Critical
🏛️ Architecture	25%	Inline response/request/parameter schemas instead of $ref to #/components	High
📝 Completeness	20%	Missing descriptions, absent examples, undocumented error codes (400, 401, 403, 500)	High
🏗️ Structure	15%	No operationId, missing tags, no semver version	Medium
🎯 Consistency	10%	Mixed camelCase/snake_case, inconsistent paths, incorrect date formats	Medium

Critical Errors Detected

🏛️ Architecture (Component Reuse)

• ARCH-01: Inline response schemas — must use $ref to #/components/schemas
• ARCH-02: Inline parameter schemas — must use $ref to #/components/schemas
• ARCH-03: Inline request body schemas — must use $ref to #/components/schemas

🔒 Security (OWASP API Top 10)

• SEC-01: Authentication schemes not defined (empty securitySchemes)
• SEC-02: API Keys in query parameters (must be in headers)
• SEC-03: HTTP instead of HTTPS
• SEC-04: additionalProperties: true (Mass Assignment risk)
• SEC-05: OAuth2 without defined scopes

🎯 Consistency (CamelCase vs Snake_Case)

• CNS-01: Mixed styles in JSON properties

  # ❌ INCORRECT
  properties:
    firstName:     # camelCase
    last_name:     # snake_case
    email_address: # snake_case
  

• CNS-02: Paths not using kebab-case (/myEndpoint vs /my-endpoint)
• CNS-03: Headers without Hyphenated-Pascal-Case
• CNS-04: Dates not in ISO8601 format (date-time)

📝 Documentation (Missing Examples)

• COM-01: Endpoints without summary or description
• COM-02: Responses without examples (example or examples)
• COM-03: Missing standard error codes (400, 401, 403, 500)
• COM-04: Incomplete metadata (contact, license)
• COM-05: Parameters without description

📦 Installation

Option 1: npm (Global)

npm install -g auditapi
auditapi audit ./openapi.yaml

Option 2: Docker

docker pull auditapi/auditapi
docker run --rm -v $(pwd):/app auditapi audit /app/openapi.yaml

Option 3: GitHub Actions

- name: Audit OpenAPI
  uses: auditapi/auditapi@v1
  with:
    file: 'openapi.yaml'
    fail-on: 'B'

🛠️ Usage

Basic Commands

# Audit a file
auditapi audit ./openapi.yaml

# Verbose mode (shows all violations)
auditapi audit ./openapi.yaml --verbose

# Fail if grade is lower than B
auditapi audit ./openapi.yaml --fail-on B

# JSON output
auditapi audit ./openapi.yaml --json

# HTML report (self-contained, offline-capable)
auditapi audit ./openapi.yaml --html -o report.html

# Save report to file
auditapi audit ./openapi.yaml --output report.json

Custom Configuration

Create a config/ directory to customize rules:

# config/ruleset.yaml
rules:
  my-custom-rule:
    description: "My custom rule"
    given: "$.paths.*"
    then:
      function: truthy
      field: description

# config/scoring.yaml
base_score: 100
weights:
  security: 0.40  # Increase security weight
  completeness: 0.20
  structure: 0.20
  consistency: 0.20

📊 Scoring System

Grade Scale

Grade	Range	Status	Meaning
A	90-100	✅ Excellent	Meets all best practices
B	80-89	✅ Good	Minor improvements needed
C	70-79	⚠️ Acceptable	Minor issues detected
D	60-69	❌ Deficient	Significant improvements required
F	0-59	❌ Failed	Critical security/quality issues

Category Weights

🔒 Security:      30% (Critical - Fatal errors cause automatic F)
🏛️ Architecture:  25% (High - Component reuse via $ref)
📝 Completeness:  20% (High - Documentation and examples)
🏗️ Structure:    15% (Medium - Tags, operationId, versioning)
🎯 Consistency:  10% (Medium - Naming conventions)

🔧 Features

• ⚡ Fast: Audits complex files in < 200ms
• 🎯 Precise: Based on Spectral + OWASP API Security
• 🐳 Containerized: Ready-to-use Docker image for CI/CD
• 🔧 Configurable: Customizable rules via YAML
• 📊 Integration: Native GitHub Actions
• 🎨 Visual: Colored terminal output + self-contained HTML reports

🏗️ Architecture

AuditAPI/
├── src/
│   ├── cli/           # Command line interface
│   ├── config/        # YAML configuration loader
│   ├── core/          # Spectral audit engine
│   ├── functions/     # Custom rules
│   ├── reporters/     # Output formatters (HTML)
│   └── types/         # TypeScript definitions
├── config/
│   ├── ruleset.yaml   # Spectral rules
│   └── scoring.yaml   # Scoring configuration
└── Dockerfile         # Multi-stage image

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/new-rule)
• Commit your changes (git commit -am 'Add new rule')
• Push to the branch (git push origin feature/new-rule)
• Open a Pull Request

📄 License

MIT © AuditAPI Team

Made with ❤️ for developers who value quality