ssl-proxy

ssl-proxy is a WireGuard-first transparent proxy with wireless audit, Redpanda-backed processing, PostgreSQL persistence and vector search. The Rust proxy and Linux Atheros Sensor publish events; the Scala Octopus coordinator owns durable ingestion and maintained projections; the Go Atheros Search service owns query APIs and embedding workers; and the SolidJS Atheros Search UI is the Integration Console.

This is Rafael Cardoso dos Santos's independently maintained backend and data-platform portfolio. Start with the Atheros Search walkthrough and trace the producer, coordinator, and query boundaries below. Schema Migrator is companion tooling for database change review. Public browser samples are synthetic; deployment readings do not establish customer outcomes or a service-level commitment.

Observed identifiers and similarity candidates do not establish physical device identity. Traffic classification is heuristic and depends on the configured path. Collection scope and remaining risks are described in the threat model.

Licensing status

This repository currently has no repository-level license file. The previous MIT badge did not establish a license grant and has been removed. Licensing needs an explicit maintainer decision; component and dependency licenses must also be reviewed before distribution.

The canonical runtime model and data ownership are documented in System Architecture. Kubernetes desired state lives only in cyber-stack/. Production is reconciled by Argo CD.

The public site, Search, Migrator and shared login use the RCLabs dark theme, with accessibility targets and manual evaluation tracked alongside the automated checks. The machine-readable palette source is theme/rclabs.tokens.json; run make theme-check after token edits and make theme-sync to regenerate surface values.

Component ownership

Component	Responsibility	Documentation
ssl-proxy	WireGuard ingress, transparent proxying, classification and sync publishing	Architecture
sync-plane	Shared Redpanda producer configuration and contracts	crates/sync-plane/
Atheros Sensor	Monitor-mode wireless capture and indirect persistence through Redpanda	Sensor README
Octopus	Durable ingestion, dedupe, evidence, leases, batching, outbox, PostgreSQL load/results and maintained projections	Octopus README
Atheros Search	Wireless-audit search platform: Go query/vector control plane and SolidJS investigation UI	Project README
Schema Migrator	Migration authoring/execution and PostgreSQL-backed internal control state	Schema Migrator README
WireGuard key rotator	Staged WireGuard key rotation and optional notifications	Rotator README

java-coordinator remains an image and Kubernetes resource identity for the Octopus service. Likewise, sync.oracle.load and sync.oracle.result are locked legacy topic names; both carry coordinator-owned PostgreSQL work and results.

Data boundaries

Canonical DDL lives in sql/postgres/ for four schemas in the external sync database:

• octopus_core
• atheros_search
• schema_migrator
• keycloak

The Integration Console is database-free. Oracle remains deprecated external target compatibility in Schema Migrator, not a stack runtime dependency.

Get started

Clone the complete workspace, including its nested repositories:

git clone --recurse-submodules https://github.com/zlovtnik/ssl-proxy.git
cd ssl-proxy

For an existing checkout, run git submodule update --init --recursive. The Search and Migrator servers depend on the canonical schemas and deployment contracts in this parent repository. Their individual checkouts are not a self-contained hosted stack.

For a database-free review, run the public site locally or use the Migrator offline commands. The site uses synthetic samples. Migrator dry-run output is shortened; retain the complete SQL source beside it. Its catalog drift comparison does not cover column definitions or nullability.

Run the targeted tests for the components you change. Validate all canonical GitOps inputs with:

make docs-check
make gitops-check

Publish the eight Kubernetes images to the repositories selected by the canonical environment (prod by default), then compare their pushed digests with the committed pins:

make publish ENV=prod

Jenkins, component publishing, and the Compose-only key rotator retain make publish-all REGISTRY=registry.example.com. HTTPS is the default. REGISTRY_PLAIN_HTTP=1 is an explicit option for an isolated local registry; it does not provide authenticated, encrypted transport. Publishing changes registry tags only; it does not mutate Git or a cluster. Diagnose desired and live state read-only with make stack-health; it uses the active Kubernetes context unless KUBE_CONTEXT is explicitly set. Record new dev digests with the printed make bump-digest-<service> commands, validate them on the local cluster, then copy the exact tested digests in a separate production promotion pull request. See the GitOps guide and operations runbook.

Local development

Database integration tests use ephemeral PostgreSQL 16 Testcontainers. No development database Compose stack is bundled; the repository-managed Wiretrap host prerequisite is documented in the PostgreSQL host guide.

(cd services/octopus && sbt test)
(cd apps/schema-migrator && sbt test)

Production readiness is determined from the production Argo CD Applications.

Topic contracts

Topic	Current meaning
sync.scan.request	Producer-to-Octopus work discovery
sync.oracle.load	Octopus-owned PostgreSQL load dispatch; legacy name
sync.oracle.result	Octopus-owned PostgreSQL load outcome; legacy name
wireless.audit	Sensor-published schema-versioned wireless events
proxy.payload_audit	Proxy payload-audit records ingested by Octopus as scan requests

Octopus also consumes wireless operational topics. Backlog listing and pruning, MAC lookup, and authorized-network operations have request/reply contracts; backlog save, mark-synced, probe-flush, and other remaining operations are one-way unless a reply topic is explicitly provisioned. See the Octopus README for consumer groups, DLQ suffixes, and the OCTOPUS_CONSUMERS_ENABLED gate.

Delivery is at least once from committed Kafka consumer-group offsets, with durable PostgreSQL dedupe and topic/partition/offset evidence.

Trim is irreversible. If a consumer group is added, it must exist before its first run or it can lose unread data. See the Redpanda daily maintenance runbook.

Common checks

cargo test -p ssl-proxy
cargo test -p sync-plane
cargo test -p atheros-sensor
(cd apps/integration-console/atheros-search && go test ./...)
(cd services/octopus && sbt test)
(cd apps/schema-migrator && sbt test)
python3 -m unittest discover -s scripts/tests -p 'test_*.py' -v

Operational references

• GitOps management and onboarding
• Jenkins image CI
• System architecture
• Atheros reporting workmap
• Reporting data and relationship contract
• Operations runbook
• Redpanda daily maintenance
• Atheros Search degraded mode
• Observability architecture
• Secret management
• Threat model