This document records the current security posture, assumptions, and operational risks of RAGU.

It is not a formal audit. It is a practical security guide for maintainers, operators, and AI agents working on the repository.

For product setup, see README.md. For operations, see OPERATIONS.md. For architecture boundaries, see ARCHITECTURE.md.

RAGU is currently best treated as:

• a local-first development or workstation tool
• suitable for trusted environments
• not yet hardened for hostile multi-user or internet-exposed deployment

The current system assumes:

• operators control the host machine
• Docker is running in a trusted local environment
• uploaded PDFs are provided by a trusted or semi-trusted user
• the Ollama and Chroma services are not exposed publicly without extra protection
• Grafana default credentials are replaced if the stack is used outside a personal machine

• environment-driven configuration instead of hardcoded secrets or paths
• non-root runtime for the app container
• local/self-hosted inference by default
• optional features like TTS degrade cleanly instead of forcing unsafe fallbacks

• no authentication layer in the Streamlit app
• no authorization model
• no TLS termination in the provided Compose stack
• some services are exposed on host ports by default
• Grafana defaults are convenience defaults, not production credentials
• cAdvisor runs with elevated access and broad host mounts
• no automated security test or dependency audit workflow yet

Current posture:

• runs as a non-root user in the container
• relies on environment variables for runtime configuration
• accepts uploaded PDFs from the UI

Risks:

• uploaded documents are still an attack surface
• no request authentication exists in front of the UI

Current posture:

• runs as an internal inference service in the Compose network
• exposed to the host by default for local use

Risks:

• if exposed beyond the local machine, any reachable user may send inference requests

Current posture:

• separate service over HTTP
• exposed to the host by default for local diagnostics and development

Risks:

• no auth is configured in the current stack
• if exposed broadly, vector data and metadata become reachable

Current posture:

• provisioned for future use
• exposed to the host by default

Risks:

• Redis should not be broadly exposed without authentication and network controls

Current posture:

• provisioned with env-configured admin credentials

Risks:

• default convenience credentials are not appropriate outside local trusted use

Current posture:

• requires broad host visibility and mounts for container metrics

Risks:

• this is one of the most sensitive services in the stack

Current posture:

• observability services are useful but expand the attack surface

Risks:

• unnecessary exposure if they are published beyond local development needs
• exporter-based metrics can reveal infrastructure details

Acceptable defaults:

• host port exposure
• local-only credentials in .env
• full observability stack enabled

Recommended minimum changes:

• place a reverse proxy or ingress with TLS and authentication in front of the app
• do not expose internal service ports unless needed
• restrict Grafana access and replace default credentials
• reconsider whether cAdvisor should be enabled

Current rule:

• do not hardcode secrets, credentials, or local absolute paths in code

Use:

• .env for local/dev runtime configuration
• stronger secret management if this project moves beyond local trusted deployment

This project depends on:

• Python packages from requirements.txt
• Docker images from public registries
• Ollama model downloads
• Piper release assets and voice model downloads during image build

Current known community or mirror dependencies:

• lucabecker42/ollama-exporter
• litetex/ghcr.google.cadvisor

These are pragmatic choices, but they should be reviewed periodically.

When making code changes:

• preserve env-driven configuration
• avoid reintroducing hardcoded local paths
• avoid exposing new host ports without documenting the reason
• prefer least-privilege container behavior
• keep optional features explicitly optional
• update docs when the attack surface changes

• remove or restrict unnecessary host port exposure for non-app services
• replace convenience credentials in any non-local deployment
• decide whether Redis should remain exposed before it is actually used
• document a safer deployment profile separate from the local dev profile

• add dependency review or vulnerability scanning
• reduce reliance on privileged observability components if possible

Before implementing infrastructure or runtime changes:

1. Read AGENT.md.
2. Read this file.
3. Check OPERATIONS.md for operational implications.
4. Update this file when you change exposed ports, credentials, trust boundaries, container privileges, or external dependencies.