IP Whitelisting Automation System

Production-Grade, Event-Driven API for Dynamic Firewall Management

---

Author

Basil Saji Mathew (BSM)
Cybersecurity Engineer / Backend Developer
Specializing in highly secure, fault-tolerant infrastructure and backend systems leveraging modern engineering and DevOps paradigms.

---

Problem Statement

Managing infrastructure-level firewalls (such as iptables, nftables, or cloud WAFs) across hybrid networks is often a highly manual, dangerous, and poorly audited process. Network administrators frequently grant temporary access to external vendors, third-party analysts, or internal developers. If this access is not properly and systematically revoked, it results in persistent whitelisting, leading to significant attack surface vulnerabilities and eventual compliance violations.

Key Features

• Role-Based Access Control (RBAC): Native authorization matrix segregating Admin, Analyst, and Viewer permissions to enforce the principle of least privilege.
• Time-Based Expiration Auto-Revocation: White-listed IP addresses are granted a strict Time-To-Live (TTL). The background queue asynchronously patches and reverts the firewall exactly at expiry without human intervention.
• Event-Driven Resilience: FastAPI never waits on subprocess overhead or system-level locks. Execution burdens are shifted cleanly to a Redis-backed Celery queueing system, ensuring API responsiveness under heavy load.
• Immutable Audit Trail: A PostgreSQL database logs every rule creation, revocation, authentication attempt, and background scheduler action, ensuring full compliance and forensic capability.
• Zero-Trust Hardened Architecture: Employs JWT generation with short lifespans, strict dependency parsing via Pydantic to neutralize layer-7 attacks, and isolation techniques to prevent Command-Injection.

Architecture Overview

graph TD
    A[Admin API Call] -->|"Validate & Verify JWT"| B(FastAPI Gateway)
    B -->|"Persist Metadata"| C[(PostgreSQL Database)]
    B -->|"Publish Setup Task"| D[Redis Message Broker]
    D --> E[Celery Background Workers]
    E -->|"Apply Subprocess Constraint"| F[Linux Firewall / iptables]
    G[Celery Beat Scheduler] -.->|"Query Expirations from PostgreSQL"| D

Loading

For an intensive breakdown of the system components and internal data flows, review the Architecture Documentation.

System Operations Flow

1. Authentication: A user authenticates via /auth/login and acquires an ephemeral JSON Web Token (JWT).
2. Rule Submission: An authorized Analyst submits a POST /rules/ request referencing an IP address (e.g., 100.22.3.4) for a specific duration (e.g., 60 Minutes).
3. Validation & State Persistence: The system verifies the user's Role and parses the IP address aggressively using Pydantic to prevent injection vectors. Upon validation, the rule is written to PostgreSQL with an Active state.
4. Asynchronous Processing: Celery queues the synchronization task. The API returns a successful response instantly to the client.
5. Firewall Modification: A Celery Worker picks up the task and securely triggers host network interfaces using parameterized commands. Corresponding webhook notifications (e.g., Discord/Slack) are initiated.
6. Automated Teardown: After the specified 60 minutes elapse, Celery Beat detects the expired row in the database and queues the teardown process automatically, returning the firewall to its default deny state.

API Interaction Examples

Registering an Administrator Account

curl -X POST "http://localhost:8000/auth/register" \
-H "Content-Type: application/json" \
-d '{"username": "bsm_admin", "password": "SecurePassword1!", "role": "admin"}'

Creating a Dynamic Whitelist Rule

curl -X POST "http://localhost:8000/rules/" \
-H "Authorization: Bearer <YOUR_JWT>" \
-H "Content-Type: application/json" \
-d '{
  "ip_address": "88.22.1.1", 
  "action": "allow", 
  "description": "Third Party Vendor Main Office",
  "expires_in_minutes": 1440
}'

See the API Documentation for complete route specifications. A configuration-ready Postman Collection is also provided in the repository root.

Installation Guide

This deployment follows a strict Docker-first methodology, handling all dependencies, network isolation, and database spin-ups natively. Ensure Docker and Docker-Compose are active on your host environment.

# 1. Clone the repository
git clone https://github.com/BasilSajiMathew/IP-Whitelist-Automation.git
cd IP-Whitelist-Automation

# 2. Configure environment variables
cp .env.example .env
# Edit .env to set secure credentials and rotating keys
nano .env 

# 3. Initialize the architecture
docker-compose up --build -d

# 4. Monitor application logs
docker-compose logs -f api celery_worker

Security Considerations

This project abstracts host shell mechanics dynamically. Due diligence is performed via standard abstraction layers avoiding manual string concatenation. Production integrations targeting local Linux host interfaces require explicitly mapped kernel permissions. Review the comprehensive Security Documentation for mandatory hardening processes prior to production distribution.

Future Roadmap

• Integrate BGP-based Blackholing features for upstream mitigation.
• Implement Threat-Feed Parsing capabilities via external generic STIX/TAXII protocols.
• Introduce Geographic auto-blocking capabilities based on MaxMind ASN mapping.
• Develop a read-only intuitive React dashboard frontend for SOC analysts.

Contributing

Contributions are essential to maintaining high-quality open-source security tools. Any contributions you make are greatly appreciated. Review our Contributing Guide for our engineering standards, pull request requirements, and semantic versioning models.

License

Distributed under the MIT License. See LICENSE for more information.

---

Built and maintained by Basil Saji Mathew (BSM)