⛨ @adhix11/endpoint-guard

Full API contract and security audit CLI for frontend + backend projects.

endpoint-guard compares frontend API usage with backend OpenAPI specs, validates paths, methods, headers, request bodies, query parameters, responses, authentication, authorization, sensitive data exposure, public write endpoints, BOLA/IDOR risks, tenant isolation risks, CORS, security headers, rate-limit risks, file upload risks, webhook safety, and generates detailed Markdown, JSON, and HTML audit reports.

Quick Start

# Run against an OpenAPI spec and frontend source
npx @adhix11/endpoint-guard audit \
  --spec ./openapi.json \
  --src ./src

# Full audit with all report formats
npx @adhix11/endpoint-guard audit \
  --spec ./openapi.json \
  --src ./src \
  --backend-src ./server/src \
  --framework loopback4 \
  --report console,markdown,json,html

# Runtime verification mode
npx @adhix11/endpoint-guard audit \
  --spec ./openapi.json \
  --base-url https://api.example.com \
  --runtime \
  --token "Bearer your-jwt-token"

# CI/CD mode — fail on critical or high issues
npx @adhix11/endpoint-guard audit \
  --spec ./openapi.json \
  --src ./src \
  --ci \
  --fail-on critical,high

Features

24 Audit Categories

| # | Feature | Category | Description | |:-:|:--|:--|:--| | 1 | Endpoint Contract | Contract | Missing endpoints, method mismatches, unused endpoints, deprecated usage | | 2 | Request Headers | Security | Missing auth headers, hardcoded tokens, wrong auth scheme | | 3 | Response Audit | Contract | Missing success/error responses, sensitive response fields | | 4 | Request Body | Contract | Missing required fields, unknown fields, type mismatches | | 5 | Query Parameters | Contract | Unknown params, sensitive data in query, no pagination | | 6 | Auth & Authorization | Security | Public endpoints, weak auth, inconsistent security | | 7 | BOLA / IDOR | Security | Object ID endpoints without ownership verification | | 8 | Tenant Isolation | Security | Cross-tenant data access risks | | 9 | CORS | Security | Wildcard origins, credentials with broad CORS | | 10 | Security Headers | Security | Missing HSTS, CSP, X-Content-Type-Options | | 11 | Rate Limiting | Reliability | No pagination, missing 429, heavy operations | | 12 | File Upload | Security | Public uploads, no size/MIME restrictions | | 13 | Error Leakage | Data | Stack traces, SQL errors, file paths in responses | | 14 | Frontend Quality | Quality | Missing try/catch, no timeout, hardcoded URLs | | 15 | Backend Source | Security | Missing auth decorators, exposed filters | | 16 | Data Exposure | Data | Sensitive fields in response schemas | | 17 | Mass Assignment | Security | Privileged fields in request bodies | | 18 | Admin Endpoints | Security | Admin paths without role protection | | 19 | Webhooks | Security | Missing signature, timestamp, idempotency | | 20 | Idempotency | Reliability | Payment/order POST without idempotency key | | 21 | Cache Control | Security | Sensitive endpoints without no-store | | 22 | OpenAPI Quality | Quality | Missing operationId, tags, schemas, descriptions | | 23 | Runtime Tests | Security | Live auth, CORS, headers, error leakage tests | | 24 | Risk Scoring | All | Aggregate score 0-100 with OWASP mapping |

CLI Options

Options:
  -s, --src <path>          Frontend source directory (default: "./src")
  -b, --backend-src <path>  Backend source directory
      --spec <path>         OpenAPI spec file path or URL
  -f, --framework <name>    Backend framework: loopback4, nestjs, express, fastify
      --base-url <url>      Base URL for runtime testing
      --runtime             Enable runtime verification mode
  -t, --token <token>       Bearer token for runtime testing
  -r, --report <formats>    Report formats: console,markdown,json,html (default: "console")
  -o, --output <dir>        Output directory for reports (default: ".")
      --ci                  CI mode — exit with code 1 on failure
      --fail-on <levels>    Severity levels that cause CI failure (default: "critical,high")
  -c, --config <path>       Config file path

Configuration File

Create .endpointguardrc.json or endpoint-guard.config.json:

{
  "src": "./src",
  "backendSrc": "./server/src",
  "spec": "./openapi.json",
  "framework": "loopback4",
  "baseUrl": "http://localhost:3000",
  "reports": ["console", "markdown", "json", "html"],

  "auth": {
    "tokenEnv": "ENDPOINT_GUARD_TOKEN",
    "requiredHeaders": ["Authorization"],
    "tenantHeaders": ["X-Tenant-Id", "X-Enterprise-Id"]
  },

  "allowPublic": [
    "POST /login",
    "POST /signup",
    "GET /health",
    "GET /openapi.json",
    "POST /webhook/*"
  ],

  "ignoreUnused": [
    "GET /health",
    "GET /openapi.json"
  ],

  "sensitiveFields": [
    "password", "token", "secret", "otp",
    "apiKey", "refreshToken", "privateKey",
    "isAdmin", "role", "permissions"
  ],

  "tenantFields": [
    "enterpriseId", "tenantId", "companyId",
    "locationOneId", "locationTwoId"
  ],

  "failOn": {
    "critical": true,
    "high": true,
    "medium": false,
    "low": false
  }
}

Report Formats

Console

Rich terminal output with colored severity indicators and structured issue details.

Markdown (endpoint-guard-report.md)

Full audit report with executive summary, risk score, issue details, endpoint inventories, and CI gate result.

JSON (endpoint-guard-report.json)

Machine-readable format for CI/CD integration and custom tooling.

HTML (endpoint-guard-report.html)

Premium dark-mode visual report with risk score card, collapsible sections, and responsive design.

Risk Scoring

Each issue is scored by severity:

| Severity | Points | Example | |:--|--:|:--| | Critical | 10 | Public write endpoint, hardcoded token | | High | 7 | Missing auth, BOLA risk, tenant isolation | | Medium | 4 | Missing pagination, unknown fields | | Low | 1 | Missing timeout, no try/catch | | Info | 0 | Unused endpoint, missing description |

Final risk score ranges:

• 80-100: Critical Risk
• 60-79: High Risk
• 30-59: Medium Risk
• 1-29: Low Risk
• 0: Clean

OWASP API Top 10 (2023) Mapping

| OWASP ID | Name | Auditors | |:--|:--|:--| | API1:2023 | Broken Object Level Authorization | BOLA/IDOR, Tenant Isolation | | API2:2023 | Broken Authentication | Auth, Request Headers, Webhooks | | API3:2023 | Broken Object Property Level Authorization | Data Exposure, Mass Assignment, Request Body | | API4:2023 | Unrestricted Resource Consumption | Rate Limit, File Upload | | API5:2023 | Broken Function Level Authorization | Auth, Admin Endpoints | | API8:2023 | Security Misconfiguration | CORS, Security Headers, Cache Control | | API9:2023 | Improper Inventory Management | Endpoint Contract, Backend Source |

Supported Frameworks

Frontend

• React (axios, fetch)
• Next.js (API routes, fetch)
• Angular (HttpClient)
• Vue (axios, fetch)
• Any JS/TS project using axios or fetch

Backend

• LoopBack 4 — decorators: @authenticate, @authorize, @get/@post, @requestBody
• NestJS — decorators: @UseGuards, @Roles, @Get/@Post, @Body
• Express — app.get(), router.post(), middleware detection
• Fastify — fastify.get(), schema definitions

Programmatic API

import { runAudit, loadConfig, parseOpenAPISpec } from '@adhix11/endpoint-guard';

// Run a full audit programmatically
const config = loadConfig({ spec: './openapi.json', src: './src' });
const report = await runAudit(config);

console.log(`Risk Score: ${report.riskScore.score}/100`);
console.log(`Issues: ${report.summary.totalIssues}`);

CI/CD Integration

GitHub Actions

- name: API Security Audit
  run: |
    npx @adhix11/endpoint-guard audit \
      --spec ./openapi.json \
      --src ./src \
      --ci \
      --fail-on critical,high \
      --report json

GitLab CI

api-audit:
  script:
    - npx @adhix11/endpoint-guard audit --spec ./openapi.json --src ./src --ci --fail-on critical,high
  artifacts:
    paths:
      - endpoint-guard-report.*

License

MIT © adhix11