# Network Security

Network egress control and isolation for Loki Mode deployments.

## Overview

This guide covers network-level security controls for restricting outbound network access from Loki Mode containers and pods to only the AI API endpoints required for operation.

## Environment Variables

The following environment variables control network egress policy enforcement:

| Variable | Default | Description |
|----------|---------|-------------|
| `LOKI_NETWORK_EGRESS_POLICY` | `unrestricted` | `unrestricted` (default), `ai-only` (restrict to AI APIs), `none` (block all outbound) |
| `LOKI_ALLOWED_HOSTS` | (empty) | Comma-separated list of additional hostnames to allow when egress policy is `ai-only` |
| `LOKI_BLOCK_METADATA_ENDPOINT` | `false` | Block cloud metadata endpoint (169.254.169.254) from within the application |

Note: These variables are reserved for future application-level enforcement. Currently, network security is implemented at the infrastructure level using Docker networks or Kubernetes NetworkPolicy.

## Docker Network Isolation

### Custom Network with ICC Disabled

Create an isolated Docker network that prevents inter-container communication and restricts egress to known AI API endpoints:

```bash
# Create an isolated bridge network with ICC disabled
docker network create \
  --driver bridge \
  --opt com.docker.network.bridge.enable_icc=false \
  --subnet 172.28.0.0/16 \
  loki-isolated
```

### Blocking the Cloud Metadata Endpoint

Cloud providers expose instance metadata at `169.254.169.254`. This endpoint can leak credentials (IAM roles, service account tokens). Block it from within the container host:

```bash
# Block metadata endpoint for containers on the loki-isolated network
iptables -I DOCKER-USER -d 169.254.169.254 -j DROP
```

### Allowing Only AI API Endpoints

Restrict outbound traffic to only the AI provider API endpoints that Loki Mode requires:

```bash
# Allow DNS resolution
iptables -A DOCKER-USER -p udp --dport 53 -j ACCEPT
iptables -A DOCKER-USER -p tcp --dport 53 -j ACCEPT

# Allow HTTPS to AI API endpoints only
# Anthropic (Claude)
iptables -A DOCKER-USER -d api.anthropic.com -p tcp --dport 443 -j ACCEPT
# OpenAI (Codex)
iptables -A DOCKER-USER -d api.openai.com -p tcp --dport 443 -j ACCEPT
# Google (Gemini)
iptables -A DOCKER-USER -d generativelanguage.googleapis.com -p tcp --dport 443 -j ACCEPT

# Drop all other outbound traffic from the isolated network
iptables -A DOCKER-USER -s 172.28.0.0/16 -j DROP
```

### Docker Compose Example

```yaml
version: "3.8"

services:
  loki:
    image: asklokesh/loki-mode:latest
    networks:
      - loki-isolated
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    volumes:
      - ./workspace:/workspace

networks:
  loki-isolated:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.enable_icc: "false"
```

Note: Docker DNS-based iptables rules resolve at rule creation time. If provider IPs change, rules must be refreshed. For production use, consider a forward proxy (e.g., Squid, Envoy) with domain-based allowlisting instead of raw iptables.

## Kubernetes NetworkPolicy

### Egress-Restricted NetworkPolicy

The following `NetworkPolicy` restricts pod egress to only the AI API endpoints and DNS:

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: loki-egress-policy
  namespace: loki
spec:
  podSelector:
    matchLabels:
      app: loki-mode
  policyTypes:
    - Egress
  egress:
    # Allow DNS resolution
    - to: []
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53
    # Allow HTTPS to AI API endpoints
    - to: []
      ports:
        - protocol: TCP
          port: 443
```

Important: Standard Kubernetes `NetworkPolicy` only supports IP-based rules, not domain names. To enforce domain-level egress control, use one of these approaches:

- **Cilium**: Supports `CiliumNetworkPolicy` with FQDN-based egress rules
- **Calico Enterprise**: Supports DNS-based network policies
- **Egress Gateway**: Route traffic through a proxy that enforces domain allowlists

### Pod Security Context

Run Loki Mode pods with a restrictive security context:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: loki-worker
  namespace: loki
  labels:
    app: loki-mode
spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: loki
      image: asklokesh/loki-mode:latest
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL
      volumeMounts:
        - name: workspace
          mountPath: /workspace
        - name: tmp
          mountPath: /tmp
      env:
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: loki-secrets
              key: anthropic-api-key
  volumes:
    - name: workspace
      emptyDir: {}
    - name: tmp
      emptyDir:
        medium: Memory
        sizeLimit: 256Mi
```

## TLS/HTTPS for Dashboard (v5.36.0)

Enable encrypted dashboard connections:

```bash
# Using environment variables
export LOKI_TLS_ENABLED=true
export LOKI_TLS_CERT=/path/to/cert.pem
export LOKI_TLS_KEY=/path/to/key.pem

loki start ./prd.md
```

Or via CLI flags:

```bash
loki dashboard start --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem
```

### Self-Signed Certificate (Development)

```bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/CN=localhost"

export LOKI_TLS_CERT=cert.pem
export LOKI_TLS_KEY=key.pem
```

### Production TLS

For production deployments, use certificates from a trusted CA:

- Let's Encrypt (free, automated)
- AWS Certificate Manager
- Your organization's internal CA

## Best Practices

### Security Checklist

- Enable TLS/HTTPS for dashboard in production
- Use network policies to restrict egress to AI API endpoints only
- Block cloud metadata endpoint (169.254.169.254)
- Run containers with read-only root filesystem
- Use non-root user (UID 1000)
- Drop all capabilities
- Enable seccomp profile
- Use separate networks for different security zones
- Monitor network traffic for anomalies

### Production Deployment

1. Enable TLS with valid certificates
2. Configure network policies or iptables rules
3. Use a reverse proxy (nginx, Envoy) for additional security headers
4. Enable audit logging to track network-related events
5. Monitor `/metrics` endpoint for unexpected traffic patterns

## Troubleshooting

### Connection to AI API Fails

```bash
# Check network policy
kubectl describe networkpolicy loki-egress-policy

# Test DNS resolution
kubectl exec -it loki-pod -- nslookup api.anthropic.com

# Check iptables rules
sudo iptables -L DOCKER-USER -n -v
```

### Dashboard HTTPS Not Working

```bash
# Verify certificate files exist and are readable
ls -la /path/to/cert.pem /path/to/key.pem

# Check certificate validity
openssl x509 -in cert.pem -text -noout

# Verify dashboard is listening on HTTPS
curl -k https://localhost:57374/health
```

## See Also

- [Authentication Guide](authentication.md) - OIDC/SSO setup
- [Authorization Guide](authorization.md) - RBAC configuration
- [Audit Logging](audit-logging.md) - Security event tracking
- [Enterprise Features](../wiki/Enterprise-Features.md) - Complete enterprise guide