An advanced, production-grade Zero Trust Network Access (ZTNA) prototype designed to compare and evaluate two distinct security architectures and access enforcement patterns:
- 🔐 Classic ZTA (Gateway-Enforced): Real-time, centralized policy enforcement at the gateway for every request, providing maximum threat control.
- ⚡ Proxyless ZTA (Agent-Assisted): Decentralized validation of usage-bound and time-bound JWT tokens with proactive push-revocation networks, providing peak performance and lower latency.
- Host-Based Telemetry: Uses OSQuery (Meta's SQL-based OS instrumentation framework) to query local system integrity, antivirus compliance, and active firewall states.
- Continuous Posture Scanning: Local background posture daemons monitor endpoint security states and stream cryptographically hashed telemetry to the Zero Trust Authority (ZTA).
- Automated Push-Revocations: Any critical posture violation (e.g. firewall disabled, running blacklisted processes) automatically invalidates all issued active user tokens and pushes revocation signals to downstream PEPs in real time.
- Thread-Safe Concurrent SQLite: Fully optimized database pipelines designed to operate reliably under concurrent Gunicorn/UWSGI workers without database lock or race conditions.
- Self-Contained Pytest Suite: An offline, zero-dependency testing framework with dynamic RSA key generation, subprocess mocking, and comprehensive end-to-end integration flow scenarios.
- Unicode-Safe & Zero-Warning Logging: Standardized Python logging architecture. Free from deprecated methods (
datetime.utcnow()), and compatible with both Windows consoles and standard container hosts.
ztna-prototype/
├── 📁 zta/ # 🛡️ Policy Decision Point (PDP) / Zero Trust Authority
│ ├── app.py # ZTA engine for policy evaluation and token issuance
│ ├── posture_service.py # Database operations, client posture, and state tracking
│ ├── anomaly_detector.py # Continuous baseline assessment and threat detection
│ └── Dockerfile # Docker specifications for the ZTA microservice
│
├── 📁 app/ # 🌐 Policy Enforcement Point (PEP) / Protected Application
│ ├── app.py # Core backend application with dual-mode PEP validation
│ └── Dockerfile # Docker specifications for the Protected Application
│
├── 📁 nginx/ # 🔀 Nginx Reverse Proxy (Classic ZTA Gateway)
│ └── nginx.conf # gateway configuration with auth_request integration
│
├── 📁 client_agent/ # 📊 Client-Side Compliance Daemon
│ └── osquery_posture_agent.py # Osquery-based telemetry collector and ZTA client agent
│
├── 📁 tests/ # 🧪 Automated Test Suite (100% Offline Coverage)
│ ├── test_authority.py # ZTA PDP logic, token issuance, and RSA validations
│ ├── test_client_agent.py # Osquery scanner, subprocess mocking, and telemetry transmission
│ └── test_integration_flow.py # End-to-end lifecycle, posture violation, and push-revocation
│
├── 📁 docs/ # 📚 Peer-Reviewed Engineering Documentation
│ ├── system_architecture.md # Detailed specification of PDP/PEP architectures
│ ├── performance_benchmarking.md # Session-Reuse (Warm) vs. Client-Isolation (Cold) analysis
│ ├── usage_token_specification.md # Cryptographic token claim specifications and security analysis
│ ├── deployment_reference.md # Complete administrative manual for setup and deployment
│ ├── posture_assessment_guide.md # Comprehensive guide for Osquery posture integrations
│ ├── logging_monitoring_guide.md # Technical breakdown of telemetry and auditing policies
│ └── changelog.md # Repository versioning and modification history
│
├── 📁 keys/ # 🔑 Cryptographic Keys (Auto-generated or Manual)
│ ├── private.pem # RSA Private key used to sign JWT tokens
│ └── public.pem # RSA Public key used to verify signatures
│
├── 📁 benchmark/ # 📊 Latency & Scalability Testing Framework
│ └── run_benchmark.sh # Automates performance benchmarking workflows
│
├── docker-compose.yml # 🐳 Microservice orchestration manifest
├── requirements.txt # 📦 Python project dependencies
├── .gitignore # ⚙️ Production git exclusions file
└── .envschema # ⚙️ Environment template for local configuration
- Philosophy: Centralized, real-time verification for every request.
- Request Flow:
Client ──> Nginx Gateway ──(auth_request)──> ZTA Authority (PDP) │ │ (Access GRANTED) (Policy Check) │ │ v v Protected Application <─────────────── [Pass/Fail] - Pros: Real-time policy changes propagate instantly; zero exposure to stale token caches.
- Cons: Introduces sub-request network latency for every request; central authority can become a bottleneck.
- Philosophy: Initial policy evaluation with fast, decentralized token validation and proactive out-of-band revocation pushing.
- Request Flow:
Client ──(Access with Cookie)──> Protected Application (PEP) │ [Local Token Verification] │ (Access GRANTED) v Serve Resource - Telemetry & Revocation Flow (Out of Band):
Client Agent ──(Telemetry)──> ZTA PDP ──(Anomaly Detected!)──> Revoke JTI │ [Push Notification] │ v Protected Application (PEP) ──> Update Blacklist - Pros: High-throughput access with near-zero latency overhead; highly scalable.
- Cons: Requires a highly reliable out-of-band token revocation propagation network to eliminate the "revocation propagation gap".
The prototype implements a strict cryptographic and policy enforcement framework:
- Authentication & Identity: User agents are verified against custom IP allowlists (
ZTA_IP_ALLOWLIST), user allowlists (ZTA_USER_ALLOWLIST), and local time-frame windows (ZTA_TIME_WINDOW). - Cryptographic Tokens: JSON Web Tokens (JWT) signed using strong RSA 2048-bit (or 4096-bit) private/public key pairs utilizing the
RS256signing algorithm. - Telemetry Assessment:
- Minimum active OS requirements.
- Active, compliant Antivirus and Host Firewall parameters.
- Device uptime thresholds.
- Running process blacklists and abnormal CPU/memory baseline spikes.
- Docker Engine v20.10+ and Docker Compose v2.0+
- Python 3.10+ (for test runners and client agents)
- OpenSSL (for manual key generation)
Clone the repository and copy the environment configuration template file:
git clone <repository_url>
cd ztna-prototype
cp .envschema .envThe .env file must reside in the root directory (ztna-prototype/.env) of the repository. Docker Compose naturally loads this file upon execution, parsing and injecting the defined parameters as OS environment variables into the ZTA PDP, Protected APP, and Nginx Gateway containers.
Key configuration areas inside .env include:
ZTA_IP_ALLOWLIST&ZTA_USER_ALLOWLIST: Sets constraints on permitted client IPs (e.g., specific subnets or*for all) and authorized user handles (e.g.,anonymous,admin).ZTA_TIME_WINDOW: Restricts resource access to defined local time intervals (format:HH:MM-HH:MM, e.g.,00:00-23:59).TOKEN_TYPE&ZTA_TTL: Governs token parameters. Set totimefor standard expiration cycles (controlled byZTA_TTLin seconds) orusagefor usage-limited single-session scopes.TLS_ENABLED: Enables or disables SSL/TLS and mTLS network authentication (trueorfalse).- Posture Assessment Rules (
POSTURE_REQUIRE_*): Defines compliance baselines such as active host firewalls, antivirus operations, running process blacklists (POSTURE_BLOCKED_PROCESSES), and performance caps (max CPU/memory utilization).
Ensure you modify these variables according to your local environment and security constraints before launching the containers.
Generate the RSA private and public key pairs required for JWT token signing and verification:
# Generate 2048-bit RSA Private Key
openssl genrsa -out keys/private.pem 2048
# Extract Public Key
openssl rsa -in keys/private.pem -pubout -out keys/public.pemBuild and run the entire microservices stack (ZTA PDP, Protected App PEP, Nginx Gateway):
# Build and run the services in the foreground
docker compose up --build
# Or launch detached in the background
docker compose up -d --buildVerify the status of the running containers:
docker compose psYou can query the respective access points locally:
- Classic ZTA (Nginx):
http://localhost:8080/ - Proxyless ZTA (Direct App):
http://localhost:5001/ - ZTA Control Plane:
http://localhost:5000/
The prototype features a robust, offline-first automated testing framework powered by unittest and pytest. It dynamically constructs cryptographic contexts, runs mock SQLite registries on disk, and simulates comprehensive multi-agent scenarios.
Create and configure an isolated local Python virtual environment:
# Create virtual environment
python -m venv .venv_test
# Activate virtual environment (Windows PowerShell)
.\.venv_test\Scripts\Activate.ps1
# Activate virtual environment (Linux/macOS)
source .venv_test/bin/activate
# Install required dependencies
pip install -r requirements.txtRun the automated test suite to verify ZTA gateways, telemetry agents, and integration flows:
# Run all tests using Pytest (Clean, Warning-Free Output)
pytest tests/
# Alternatively, execute using Python's native Unittest framework
python -m unittest tests/test_authority.py
python -m unittest tests/test_client_agent.py
python -m unittest tests/test_integration_flow.pyTo run dynamic system integration scenarios executing simulated device scans and automatic security revocations:
# Execute automated baseline and posture check tests
python test_posture_architectures.py
# Or use the quick helper script
./quick_test.shTo measure and compare the latency, throughput, and efficiency profiles of both Classic and Proxyless architectures:
# Access the benchmark environment
cd benchmark/
# Run the complete automated performance test suite
./run_benchmark.shDetailed performance analysis is stored in the docs/performance_benchmarking.md file.
POST /register_app— Register protected microservices to receive real-time push revocations.POST /login— Standard user authentication and initial policy evaluation.POST /policy_login— Transparent bootstrap login interface for service-to-service validation.GET /auth_redirect— Handles transparent redirects and token issuance for Proxyless mode.POST /revoke— Revokes specific JWT identifiers (JTIs) and triggers out-of-band updates.POST /api/posture/register— Registers device agents for dynamic posture tracking.POST /api/posture/update— Receives continuous telemetry updates from client agents.
GET /— Serves the protected resource (Direct Token-verification in Proxyless; Gateway-trusted in Classic).POST /revoke— Internal endpoint to receive out-of-band token blacklisting push updates.
Comprehensive engineering specifications are located under the /docs root directory:
- 🛡️ docs/system_architecture.md — Architectural design, PDP/PEP topology, and comparison matrices.
- 📈 docs/performance_benchmarking.md — Rationale, methodologies, and analysis of warm vs. cold connections.
- 🔐 docs/usage_token_specification.md — Dynamic usage tokens threat model and concurrent decrement verification.
- 🚀 docs/deployment_reference.md — Step-by-step setup guides, orchestration parameters, and troubleshooting guides.
- 📊 docs/posture_assessment_guide.md — Osquery compliance criteria, baseline definitions, and anomaly thresholds.
- 🔬 docs/logging_monitoring_guide.md — Auditing standards, structured log hierarchies, and telemetry formats.
- 📜 docs/changelog.md — Documented versions, updates, refactoring checkpoints, and audit logs.