<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Securing Kubernetes Secrets — API Reference

## Agent CLI

```bash
# Run audit
node scripts/agent.js --action audit --output results.json

# Filter by severity
node scripts/agent.js --action audit --severity critical --output critical.json

# Target specific namespace
node scripts/agent.js --action audit --namespace production --output prod-audit.json
```

## Output Format

```json
{
  "tool": "k8s-secrets-auditor",
  "version": "1.0",
  "timestamp": "ISO8601",
  "total_findings": 0,
  "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0},
  "findings": []
}
```

## Finding Schema

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Finding category |
| `severity` | string | critical, high, medium, low |
| `desc` | string | Human-readable description |
| `namespace` | string | Kubernetes namespace |
| `pod` | string | Pod name (if applicable) |
| `container` | string | Container name (if applicable) |

## kubectl Commands

```bash
# List pods with security context details
kubectl get pods -A -o json | jq '.items[] | {
  ns: .metadata.namespace,
  pod: .metadata.name,
  containers: [.spec.containers[] | {
    name: .name,
    privileged: .securityContext.privileged,
    runAsNonRoot: .securityContext.runAsNonRoot
  }]
}'

# Check namespace labels
kubectl get namespaces --show-labels

# Describe resource
kubectl describe pod POD_NAME -n NAMESPACE
```

## References

- [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/)
- [Encrypting Secret Data at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)
- [Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/)
- [External Secrets Operator](https://external-secrets.io/)
