Security Audits & Hooks
Relevant source files
The following files were used as context for generating this wiki page:
Security Audits and Hooks in Nyansa establish a multi-layered defense to prevent secret leakage and unauthorized network exposure. The system enforces verifiable security rules during development and deployment phases, ensuring that no internal service is reachable from the public internet and no credentials reside in the git history.
The project implements these protections through a combination of Git pre-push hooks, automated exposure checks for Docker Compose profiles, and strict secret scanning. These measures complement the runtime security features, such as internal network isolation and token-based authentication for the memory-api service.
Sources: README.md:65-98, README.md:105-131
Git Hooks Architecture
Nyansa utilizes Git hooks to automate security validation on the developer's local machine before changes are pushed to a remote repository. The installation script, scripts/install-hooks.sh, links the project's hook scripts to the .git/hooks directory.
Pre-push Validation Flow
The pre-push hook acts as a final gatekeeper. It triggers the secret scanning and build validation scripts. If any audit fails, the hook aborts the git push command, preventing insecure code from leaving the local environment.
The flow ensures that every commit is audited for secrets and network exposure before it is considered for deployment.
Sources: scripts/install-hooks.sh, README.md:100-103, README.md:144-145
Secret Scanning Logic
The scripts/check-secrets.sh utility identifies potential security breaches by scanning tracked files for sensitive data. It prevents the accidental inclusion of environment files and specific token patterns in the repository history.
- File Pattern Blocking: The script explicitly refuses the inclusion of
.envfiles. - Token Detection: It scans for high-entropy strings and hex-encoded tokens that match the length and format of Nyansa's required secrets (e.g., 32-character hex strings).
- Version Control Integration: It primarily audits the
HEADcommit or specific ranges to ensure only current changes are validated.
Sources: scripts/check-secrets.sh, README.md:92, README.md:174
Network Exposure Auditing
The scripts/check-exposure.sh script validates that the Docker infrastructure does not inadvertently expose internal services to the public internet. This is critical because Docker often bypasses host firewalls like UFW when publishing ports.
Exposure Rules and Profiles
The auditor checks all 9 possible profile combinations (CPU, GPU-Nvidia, GPU-AMD paired with Public, Tailscale, or no access profile). It ensures that only the Caddy reverse proxy publishes ports to 0.0.0.0.
| Service | Allowed Exposure | Constraint |
|---|---|---|
| nyansa-caddy-public | 80, 443 | Published on all interfaces |
| nyansa-n8n | 5678 | Bound to 127.0.0.1 (Loopback) |
| nyansa-open-webui | 3000 | Bound to 127.0.0.1 (Loopback) |
| nyansa-postgres | None | Internal network only |
| nyansa-qdrant | None | Internal network only |
| nyansa-memory-api | None | Internal network only |
Sources: scripts/check-exposure.sh, docker-compose.yml:148-150, docker-compose.yml:226-227, README.md:82-88
Validation Process
The audit uses docker compose config to resolve the final state of the docker-compose.yml for each profile before inspecting the ports definitions.
Sources: scripts/check-exposure.sh, scripts/build-publish.sh:120-125
Build and Release Validation
The scripts/build-publish.sh script prepares an immutable release folder. It includes security steps to ensure the production artifacts are clean and correctly configured.
- Dependency Export: It uses
git archiveto export files, ensuring that uncommitted local files or ignored.envfiles are never included in the release. - Secret Stripping: It verifies that the resulting release folder contains no
.envfiles. - Release Pinning: It replaces the
${NYANSA_RELEASE:-dev}placeholder indocker-compose.ymlwith the actual commit SHA to ensure the stack runs the exact image built from that commit. - Final Exposure Audit: It runs
check-exposure.shagainst the generated release folder using.env.exampleto confirm the final production configuration is secure.
Sources: scripts/build-publish.sh:1-25, scripts/build-publish.sh:105-115, scripts/build-publish.sh:120-125
Runtime Authentication
The memory-api service implements internal security measures to protect the vector store and search endpoints.
- Bearer Token Authentication: The service requires an
Authorization: Bearer <TOKEN>header for all routes except/health. - Constant-Time Comparison: It uses
timingSafeEqualto compare provided tokens against the configuredMEMORY_API_TOKEN, preventing timing attacks. - Container Hardening: The container runs with a read-only filesystem, dropped Linux capabilities, and no privilege escalation.
Sources: services/memory-api/src/app.ts:54-63, docker-compose.yml:254-257, README.md:79-80
Ingestion Security Data Flow
Internal communications use specific secrets (MEMORY_API_TOKEN and QDRANT_API_KEY) even within the isolated nyansa Docker network.
Sources: services/memory-api/src/app.ts:54-63, docker-compose.yml:213-214, docker-compose.yml:262-263
Summary
Nyansa's security posture relies on preventative checks that occur before code deployment. By automating secret scanning and network exposure audits through Git hooks and build scripts, the project ensures that security policies are enforced consistently across all hardware and access profiles. Runtime protections, including container hardening and constant-time token validation, provide defense-in-depth for the internal service architecture.