Skip to content

api.md

Latest commit

 

History

History
95 lines (78 loc) · 3.22 KB

api.md

File metadata and controls

95 lines (78 loc) · 3.22 KB
Raw

API Specification

The RESTful API provides highly structured endpoints for authentication processing and firewall rule lifecycle management.

Maintained by: Basil Saji Mathew (BSM)

OpenAPI Documentation

When the application is active in a development environment, the interactive Swagger interface is automatically generated and accessible via /docs and the ReDoc interface is available at /redoc.

1. Authentication Services

Register New User

  • Endpoint: POST /auth/register
  • Visibility: Public (Should be disabled or protected via internal VPC in Production)
  • Description: Creates a new structural account within the system. Passwords are mathematically hashed via bcrypt round processing prior to storage.
  • Payload Structure: 
    {
  "username": "network_admin",
  "password": "ComprehensiveSecurityPassword2026",
  "role": "admin"
}
  • Acceptable Roles: admin, analyst, viewer

Issue Authentication Token

  • Endpoint: POST /auth/login
  • Description: Complies with OAuth2 standard formats. Issues a JSON Web Token (JWT) Bearer token required for all subsequent authenticated endpoints.
  • Payload Type: application/x-www-form-urlencoded
  • Parameters: username, password
  • Response: 
    {
  "access_token": "eyJhb...",
  "token_type": "bearer"
}

2. Rule Configuration Engine

Authentication Required: Bearer JWT

Allocate Whitelist Target

  • Endpoint: POST /rules/
  • Role Prerequisite: admin or analyst
  • Description: Persists a target IP and schedules firewall adjustments. Instantly logs an audit trail. An active rule covering the identical IP will correctly trigger an HTTP 400 rejection to prevent duplication anomalies.
  • Payload Structure: 
    {
  "ip_address": "192.168.1.100", 
  "action": "allow", 
  "description": "Remote diagnostic engineer node",
  "expires_in_minutes": 120
}

List Configuration State

  • Endpoint: GET /rules/
  • Role Prerequisite: admin, analyst, or viewer
  • Query Parameters:
    • active_only (bool, default true): Filters response to display only rules currently impacting network traffic.
  • Response Output: Returns an array containing detailed metadata regarding system rules and their absolute expiration chronological timestamps.

Revoke Whitelist / Terminate Access

  • Endpoint: DELETE /rules/{rule_id}
  • Role Prerequisite: admin
  • Description: Forcibly deactivates a rule prior to its scheduled TTL execution and signals the backend background worker to pull down local firewall bindings.

3. Compliance and Auditing

Authentication Required: Bearer JWT

Read Immutable Audit Log

  • Endpoint: GET /rules/logs
  • Role Prerequisite: admin
  • Description: Dumps raw, immutable chronological logs tracking every modification to the system. Extensively utilized to generate SOC compliance reporting.
  • Response Outline: 
    [
  {
    "id": 105,
    "user_id": 1,
    "action": "CREATE_RULE",
    "details": "Created allow rule for 192.168.1.100. Expires: 2026-04-02 12:00:00",
    "ip_address": "192.168.1.100",
    "timestamp": "2026-04-02T10:00:00Z"
  }
]