Security Best Practices

12.1 API Key Management

The API key is the primary authentication credential. Follow these practices:

• Never embed the key in source code, Dockerfiles, or image layers. Use environment variables or secrets managers.
• Rotate regularly: update API_KEY in the environment and restart the API. Existing sessions are invalidated immediately.
• Minimum length: use at least 32 random characters. Generate with openssl rand -hex 32.
• Scope access: for automated tooling (CI, Ansible, Terraform), create a dedicated key separate from the key used by operators.
• Personal Access Tokens (PAT): for per-user CLI access, issue PATs via meshq login rather than sharing the master API key. See §4.5.

12.2 Network Exposure

The API process listens on all interfaces by default. In production:

• Place the API behind a reverse proxy (nginx, Traefik, or an AWS ALB) that terminates TLS.
• Restrict inbound traffic to the proxy only; do not expose port 8000 directly.
• Use TLS 1.2 or higher. Let's Encrypt / ACM certificates are free and automatic.
• Enable HTTP Strict Transport Security (HSTS) on the proxy.

Kubernetes network policy

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: meshoptixiq-api
spec:
  podSelector:
    matchLabels:
      app: meshoptixiq-api
  policyTypes: [Ingress, Egress]
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: ingress-nginx
  egress:
    - to:
        - podSelector: {matchLabels: {app: neo4j}}
    - to:
        - podSelector: {matchLabels: {app: redis}}
    - ports:
        - port: 443
          protocol: TCP

12.3 Secrets Management

12.4 Role-Based Access Control

When multiple teams use the same MeshOptixIQ instance, enable RBAC to limit which queries each team can execute. See §13.6 for configuration details. Key recommendations:

• Default to a deny-all policy; explicitly grant access to required query patterns.
• The helpdesk role should be limited to read-only summary and hygiene queries.
• The security role should have access to firewall and path-analysis queries.
• Only admin and architect roles should be allowed to execute update_device_metadata.

12.5 Audit Logging

Enterprise tier includes structured audit logging for every query execution, login, and administrative action. Enable it:

AUDIT_LOG_ENABLED=true
AUDIT_LOG_BACKEND=splunk
SPLUNK_HEC_URL=https://splunk.corp.example.com:8088
SPLUNK_HEC_TOKEN=<hec-token>

Each audit record includes: timestamp, username/API key fingerprint, client IP, query name, execution duration, row count, and plan tier.

12.6 Data Classification

The graph database contains sensitive network topology data. Treat this data according to your organisation's confidential classification:

• Enable Neo4j authentication and encrypt the bolt connection (NEO4J_URI=bolt+s://…).
• Restrict Neo4j port 7687 to the API containers only; do not expose it externally.
• Encrypt Neo4j data at rest using full-disk encryption on the volume.
• For PostgreSQL backend: enable ssl=require in the connection string.
• Regularly rotate database credentials independently from the MeshOptixIQ API key.