GoTLS Proxy — Stateful-Ready TLS Trust Gateway

Overview

GoTLS Proxy is a hardened TLS reverse proxy designed for browser trust scoring, bot mitigation, and traffic filtering.

It performs deep TLS and HTTP inspection, integrates a real browser renderer (Puppeteer) for behavioral validation, and routes traffic based on a stateless trust scoring system.

The system is built with security-first principles:

Dedicated non-root service user
Strict filesystem permissions
Loopback-isolated internal services
Systemd hardening

Architecture

The project evolved through multiple iterations.

Version 1 (Initial Design)

This diagram illustrates the original trust-flow architecture developed during the first implementation.

Version 2 (Production Architecture)

After implementing production deployment, Redis-backed IP banning, automated TLS certificate synchronization, Linux service hardening, and observability, the architecture evolved into the following production-ready design.

High-Level Request Flow

Client
  ↓
TLS Edge (GoTLS Proxy :443)
  ↓
Stateless Trust Engine
  ↓
Node Renderer (127.0.0.1:9222)
  ↓
Internal Renderer Backend (127.0.0.1:4444)
  ↓
Main Backend (127.0.0.1:4443)

Core Features

🔐 TLS Fingerprinting

JA3-based TLS fingerprint extraction
ALPN + cipher behavior validation
Early handshake filtering (pre-HTTP)

🧠 Stateless Trust Scoring

Each request is evaluated independently using:

TLS fingerprint consistency (JA3)
User-Agent validation
Header structure & coherence
Request behavior patterns (per-request only)

No session tracking (yet) — fully stateless design.

🌐 Browser Verification (Renderer)

Headless Chromium via Puppeteer
Executes JavaScript
Generates real browser signals:
- navigator properties
- canvas interaction
- timing behavior

Used to:

Verify suspicious clients
Boost trust scoring confidence

🔁 Reverse Proxy Routing

Trusted traffic → forwarded to backend
Untrusted traffic → rejected (403 Forbidden)

Supports:

Header forwarding
Real client IP visibility
Debug inspection via temporary backend

🧪 Temporary Debug Backend

A built-in testing backend provides:

Request headers
Cookies
Client IP
Method + path

Used to:

Validate proxy routing
Debug trust decisions
Confirm no 502 errors

🔐 TLS Certificate Management

GoTLS runs as a non-root service user (SERVICE_USER).

Production TLS certificates are stored in:

/etc/gotls-proxy/certs/

Files:

fullchain.pem
privkey.pem

GoTLS reads certificates from its own certificate directory rather than directly from the Let's Encrypt directory.

Certificate synchronization is fully automated through the Certbot deploy hook located at:

/etc/letsencrypt/renewal-hooks/deploy/reload_gotls_proxy.sh

During each successful renewal:

Renewed certificates are copied into the GoTLS certificate directory.
Ownership and permissions are applied for the SERVICE_USER service user.
The GoTLS service is restarted so the new certificate is served immediately.

🔄 TLS Certificate Automation

Certbot (webroot mode)
Automatic certificate renewal
Deploy hook automatically synchronizes renewed certificates
GoTLS service automatically restarts after certificate synchronization

After each successful Let's Encrypt renewal, the deploy hook:

Copies the renewed certificate into /etc/gotls-proxy/certs/
Applies secure ownership and permissions for the SERVICE_USER service user
Restarts the GoTLS service so the latest certificate is served immediately

This allows GoTLS to run as a non-root service while always serving the latest TLS certificate without manual intervention.

📊 Logging & Observability

Structured logs via journald
Application log:
- /var/log/gotls-proxy/gotls.log
Trust scoring output:
- client IP
- score
- decision (allowed / filtered)
Rate-limit events
Renderer failures
Proxy decisions

Screenshots

Service Startup

Shows all production services running successfully.

Initial State

Final State

TLS Certificate Validation

Demonstrates successful TLS handshake and certificate verification.

Initial State

Final State

TLS Error Monitoring

Illustrates observable TLS handshake failures.

Initial State

Final State

Request Blocking

Shows trust threshold enforcement.

Initial State

Final State

Metrics Endpoint

Demonstrates Prometheus metrics exposure.

Trusted Request Processing

Illustrates successful request routing.

Initial State

Final State

Demonstration

5 Minute Project Demonstration

A short walkthrough demonstrating:

system startup
TLS validation
trust scoring
metrics
backend routing
observability

Video:

Watch Demo Video

Full Technical Walkthrough (32 Minutes)

Complete engineering walkthrough covering:

architecture
Linux deployment
renderer integration
metrics
debugging
observability
production design decisions

Video:

Watch Technical Walkthrough

Documentation

Detailed engineering documentation is available under:

docs/architecture/
docs/testing/
docs/security/
docs/deployment/
docs/reports/

These documents describe architecture evolution, testing methodology, deployment procedures, security decisions, and project reports.

Project Structure

/opt/gotls-proxy/
├── main.go
├── verify_challenge.go
├── go.mod
├── botpage.html
├── README.md
├── .env
├── .env.example
├── .gitignore
├── config.example.json
│
├── node_renderer/
│   ├── package.json
│   └── renderer.js
│
├── backend/
│   └── renderer_page.html
│
├── internal_renderer_backend/
│   └── main.go
│
├── temp_backend/
│   └── server.go
│
├── scripts/
│   ├── install_deps.sh
│   └── build_and_install.sh
│
├── systemd/
│   ├── gotls-proxy.service.example
│   ├── node-renderer.service.example
│   └── internal-renderer-backend.service.example

/etc/gotls-proxy/
├── config.json
└── certs/
    ├── fullchain.pem
    └── privkey.pem

/etc/systemd/system/
├── gotls-proxy.service
├── node-renderer.service
└── internal-renderer-backend.service

/etc/letsencrypt/renewal-hooks/deploy/
└── reload_gotls_proxy.sh

/etc/logrotate.d/
└── gotls-proxy

/etc/prometheus/rules/
└── gotls.rules.yml

/var/lib/gotls-proxy/
└── acme-challenges/

/var/log/gotls-proxy/
└── gotls.log

Services (systemd)

gotls-proxy → TLS edge + trust engine
node-renderer → Puppeteer browser engine
internal-renderer-backend → renderer-only backend

Security Model

Initial Security Model

No root runtime
Loopback-only internal services
Strict filesystem permissions

Current Production Security Model

Dedicated non-login service account (SERVICE_USER)
Non-root execution model
Loopback-isolated internal services
systemd hardening:
- ProtectHome=true
- PrivateTmp=true
- NoNewPrivileges=true
Strict filesystem permissions:
- configs → 750
- runtime directories → 700
Redis trust persistence
UFW firewall protection
Automated TLS certificate deployment

Security Features

🛡️ Automated IP Banning

Clients exceeding configured trust or abuse thresholds are automatically placed into temporary Redis-backed IP bans.

Current behavior:

Automatic ban creation
Configurable TTL (automatic expiration)
Trust threshold enforcement
Redis persistence during active bans

Verification

redis-cli KEYS "banned:*"
redis-cli TTL banned:<ip>

🔥 Host Firewall Protection (UFW)

Ubuntu UFW protects the host using a default-deny inbound policy.

Only the following inbound services are permitted:

SSH (22/TCP)
HTTP (80/TCP)
HTTPS (443/TCP)

All other inbound ports remain blocked unless explicitly allowed.

Certificate Setup

Certificates are issued using:

certbot certonly --webroot \
  -w /var/lib/gotls-proxy/acme-challenges \
  -d northgateworkspace.com

Auto-reload handled via deploy hook:

/etc/letsencrypt/renewal-hooks/deploy/reload_gotls_proxy.sh

Testing & Validation

Service Status Verification

sudo systemctl status gotls-proxy node-renderer internal-renderer-backend --no-pager

TLS Verification

openssl x509 -in /etc/letsencrypt/live/northgateworkspace.com/fullchain.pem -noout -dates

Live Certificate Check

curl -vk https://northgateworkspace.com 2>&1 | grep "expire date"

Backend Routing Test

curl -k https://northgateworkspace.com/

Renderer Health

curl http://127.0.0.1:9222/health

Metrics Verification

curl http://127.0.0.1:9100/metrics | grep gotls_requests_total

Redis IP Ban Verification

redis-cli KEYS "banned:*"

redis-cli TTL banned:<ip>

Trust Decision Verification

journalctl -u gotls-proxy --since today | grep '"trusted client allowed"'

journalctl -u gotls-proxy --since today | grep '"blocked by trust threshold"'

TLS Error Monitoring

journalctl -u gotls-proxy --since today | grep "TLS handshake error"

Logs

journalctl -u gotls-proxy -f
journalctl -u node-renderer -f
journalctl -u internal-renderer-backend -f

Current Capabilities

Initial Capabilities

TLS reverse proxy routing
Stateless trust scoring
Browser-based verification (Puppeteer)
Debug backend inspection

Current Production Capabilities

✅ TLS fingerprint filtering (JA3/JA4)

✅ Stateless trust engine

✅ Redis-backed IP banning

✅ Reverse proxy routing

✅ Browser-based verification (Puppeteer)

✅ Automated TLS certificate synchronization

✅ Metrics and observability endpoints

✅ Linux service hardening

✅ Non-root service execution

✅ UFW host firewall integration

✅ Production systemd deployment

Limitations (Intentional)

No session tracking (stateless only)
No cookie continuity scoring
No advanced HTTP WAF rule engine (basic request filtering only)

Future Enhancements (Planned)

Identity & Access Management

OAuth 2.0 authentication
OpenID Connect (OIDC)
JWT access tokens
Refresh token rotation
Role-Based Access Control (RBAC)
Secure session management

Application & API Security

OWASP Top 10 protections
OWASP API Security Top 10 protections
API Gateway integration
Cookie continuity scoring
Trust persistence engine
Redis session tracking
Browser behavior reuse analysis
Fingerprint history tracking
IP reputation persistence
Trust accumulation logic
Challenge-solving memory
Behavioral timing analysis
Advanced anomaly detection

Traffic Routing & Proxy Infrastructure

SOCKS5 outbound proxy support
Proxy authentication
Proxy health monitoring
Automatic proxy failover
Exit IP reputation tracking
Outbound routing policies

Host Firewall Enforcement

Dynamic UFW rule management
Automatic IP blocking
Automatic IP unblocking
Redis-to-UFW synchronization
Firewall rule synchronization
Firewall event logging
Application-driven firewall decisions

Advanced HTTP WAF

SQL Injection detection
Cross-Site Scripting detection
Path Traversal detection
Remote/Local File Inclusion detection
Command Injection detection
Server-Side Request Forgery detection
Malicious file upload detection
HTTP request normalization
Header validation
Request body inspection
Rule-based attack signatures
Custom rule engine
Threat intelligence integration

Data & Persistence

PostgreSQL integration
Persistent trust database
Reputation storage
Audit logging

Detection & Response

Vulnerability management workflow
Incident response procedures
Enhanced monitoring and alerting
Grafana monitoring dashboards

Cloud & Deployment

Docker containerization
CI/CD pipelines
AWS deployment
Infrastructure as Code
Deployment automation

Business Platform Integration

Secure Business Platform integration
Identity-aware reverse proxy
OAuth/OIDC trust propagation
JWT validation support
Business application request protection
API trust enforcement
Authenticated session inspection
Audit event forwarding

Purpose

This project demonstrates:

Real-world edge security engineering
TLS fingerprinting and traffic filtering
Reverse proxy architecture design
Browser-based verification techniques
Secure Linux service isolation
Production observability and metrics
Infrastructure hardening practices
Practical bot mitigation techniques

Author Notes

This system was built iteratively with a strong focus on:

Security correctness
Operational observability
Production-grade deployment practices
Clean architectural separation
Incremental capability evolution

Each component can be tested independently, making the system highly maintainable, extensible, and suitable for further engineering phases including:

Docker deployment
CI/CD integration
Stateful trust persistence
Full HTTP WAF capabilities

License & Usage

This repository is provided for portfolio and evaluation purposes only.

Permission is granted to view, clone, and execute the project for educational and evaluation purposes.

Modification, redistribution, commercialization, or incorporation into other projects is prohibited without prior written authorization from the author.

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
internal_renderer_backend		internal_renderer_backend
node_renderer		node_renderer
scripts		scripts
systemd		systemd
temp_backend		temp_backend
.env.example		.env.example
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
botpage.html		botpage.html
config.example.json		config.example.json
go.mod		go.mod
go.sum		go.sum
main.go		main.go
verify_challenge.go		verify_challenge.go

Latest commit

History

Folders and files

Repository files navigation

GoTLS Proxy — Stateful-Ready TLS Trust Gateway

Overview

Architecture

Version 1 (Initial Design)

Version 2 (Production Architecture)

High-Level Request Flow

Core Features

🔐 TLS Fingerprinting

🧠 Stateless Trust Scoring

🌐 Browser Verification (Renderer)

🔁 Reverse Proxy Routing

🧪 Temporary Debug Backend

🔐 TLS Certificate Management

🔄 TLS Certificate Automation

📊 Logging & Observability

Screenshots

Service Startup

Initial State

Final State

TLS Certificate Validation

Initial State

Final State

TLS Error Monitoring

Initial State

Final State

Request Blocking

Initial State

Final State

Metrics Endpoint

Trusted Request Processing

Initial State

Final State

Demonstration

5 Minute Project Demonstration

Full Technical Walkthrough (32 Minutes)

Documentation

Project Structure

Services (systemd)

Security Model

Initial Security Model

Current Production Security Model

Security Features

🛡️ Automated IP Banning

Verification

🔥 Host Firewall Protection (UFW)

Certificate Setup

Testing & Validation

Service Status Verification

TLS Verification

Live Certificate Check

Backend Routing Test

Renderer Health

Metrics Verification

Redis IP Ban Verification

Trust Decision Verification

TLS Error Monitoring

Logs

Current Capabilities

Initial Capabilities

Current Production Capabilities

Limitations (Intentional)

Future Enhancements (Planned)

Identity & Access Management

Application & API Security

Traffic Routing & Proxy Infrastructure

Host Firewall Enforcement

Advanced HTTP WAF

Data & Persistence

Detection & Response

Cloud & Deployment

Business Platform Integration

Purpose

Author Notes

License & Usage

About

Topics