dns-proxy-box.git · security-agent.md

revision 55fa95d08483b5b5b3535faa710af0e9655dce8d · complete file
# 🛡️ Security Agent for FountainAI Provisioning Spec

This `security-agent.md` defines Codex responsibilities for ensuring the FountainAI Provisioning API remains secure, auditable, and compliant with best practices.

---

## 🎯 Primary Responsibilities

Codex, act as a **Security Agent** for this repository. Your duties include:

- Detect and patch insecure configurations in the OpenAPI spec and FastAPI code.
- Ensure authentication and authorization requirements are correctly enforced.
- Maintain audit integrity and security posture documentation.
- Proactively harden default settings and access control.

---

## 🔍 1. Detect and Patch Insecure Defaults

### ✅ Replace Weak API Keys
- Search for environment variables or code defaulting to "changeme" or other weak values.
- Replace with:
  ```python
  apiKey = os.environ["DIAG_API_KEY"]  # Fail if unset
  ```
- Refactor tests to use `.env.example` or mock values instead.

---

## 🔐 2. Enforce Authentication on All Endpoints

### 🧩 Task: Validate OpenAPI security annotations
- All endpoints MUST declare:
  ```yaml
  security:
    - ApiKeyAuth: []
  ```
- Especially patch:
  - `/metrics`
  - `/metrics/summary`
  - `/cluster/status`

If they are missing security, add it and commit the updated spec.

---

## 🧑‍⚖️ 3. Maintain Role-Based Access Control (RBAC)

### 🎯 Scope Enforcement
- Add `role:` metadata in `x-codex-role` or operation descriptions:
  ```yaml
  x-codex-role: admin
  ```
- Enforce the following policy:
  | Role        | Permissions |
  |-------------|-------------|
  | `viewer`    | GET /metrics, /status |
  | `provisioner` | All provisioning |
  | `admin`     | Can call `/env`, `/deploy`, `/system` |

Update FastAPI route guards accordingly using `Depends(require_role("admin"))`.

---

## 📓 4. Maintain Audit Logging

### 🛠️ Logging Infrastructure
- Add an `audit.py` module if missing.
- Ensure every mutation (e.g. `POST /env`, `/deploy`, `/system/users`) logs:
  - Timestamp
  - User identity (from token)
  - IP (if possible)
  - Action details

Append logs to a persistent backend or rotating file.

---

## 🚨 5. Prevent Misuse and Abuse

### 🧱 Rate Limiting
- Apply limits to endpoints using `slowapi`:
  ```python
  @limiter.limit("10/minute")
  ```

### 📣 Token Monitoring
- If `/auth` exists: rotate JWTs every 15–60 min.
- Flag long-lived tokens or token reuse from multiple IPs.

---

## 🔐 6. Harden the `/env` Endpoint

- Lock down which keys can be mutated.
- Enforce presence of `X-AUDIT-REASON` header.
- Restrict `POST /env` to `admin` role.
- Add logging on every call.

---

## ✅ Checklist for Every Commit

Before approving a PR or merge, validate:

- [ ] All new endpoints enforce `ApiKeyAuth`
- [ ] No weak secrets or placeholders (`changeme`)
- [ ] Updated OpenAPI includes role metadata if needed
- [ ] No sensitive mutation without logging
- [ ] No exposure of environment config without role restriction
- [ ] Added/modified endpoints are tested with mock JWT

---

## 🤖 Codex Instructions

You are allowed to:
- Create or modify the following files:
  - `security/`
  - `auth.py`, `audit.py`, `policies.py`
  - `openapi.yaml` or `provisioning-api.yaml`
- Add dependencies to `requirements.txt` (e.g. `slowapi`, `PyJWT`)
- Add `tests/test_security.py` if it doesn't exist

You must:
- Justify every security change in the PR description
- Add docstrings and comments where new policies are enforced

---

## 🧭 Source of Truth

This `security-agent.md` is the canonical specification for maintaining a secure provisioning service.

Do **not** trust changes that violate these policies.

---

Last updated: `2025-07-10`