Answer a security questionnaire

# Decosa security questionnaire answerer: use the hosted API

You are wiring Decosa's questionnaire answerer into this project. It takes a company's approved answer library and a
buyer's security questionnaire and fills each question with approved text only: an open model chooses approved answers
or policy passages, any sentence it changes is checked against the source (and reverted if anything was added), approved
answers are checked against the policies they cite, and questions with nothing approved behind them are left for a
person. Every model call has its own signed receipt, and each run ends with a review record signed by the server. Use
only what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- The hosted API keeps nothing, but a library describes a company's security posture: for real policies, self-host.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`. Up to 200 questions a run.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "security-questionnaire"}` returns
   `{"token", "expires_at", "budget"}`. a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz); each session has a token allowance (its `budget`); up to 60
   questions a run. A run needs 250 tokens of budget per question to start (402 otherwise). One run at a time per token.

## Inputs
- `questionnaire`: `{"questions": [{"id", "section", "question"}]}`, or `{"file": {"name": "buyer.xlsx", "b64": "..."}}`
  (XLSX or CSV: the first sheet with a header containing "question"), or `{"text": "one question per line"}`.
- `library`: `{"entries": [{"id", "question", "answer", "yes_no"?, "sources"?: ["POL-ENC"], "origin"?}],
  "documents": [{"id": "POL-ENC", "title", "kind": "policy"|"report"|"faq", "text"}], "files"?: [{"name", "b64"}]}`.
  A CSV or XLSX file in `files` needs Question and Answer columns (optional ID, Yes/No, Source, Origin).
- Limits: 1,500 entries, 25 documents (400,000 characters in total), 3 MB per file, 8 MB per request.
- `POST /questionnaire/parse` (token) with either input returns what will be used, with no model call; it lists
  citations that point at documents you did not send.

## Run
`POST /questionnaire/answer` (token) with `{"questionnaire": ..., "library": ...}`.
- JSON by default: `{counts, items: [{i, id, section, question, status, answer, yes_no, sources: [{ref, kind, label, text}],
  fit, reason, adaptation: {mode, proposed?, why?}, source_check: {state, docs} | null, receipt_ids}], receipts, record, budget, note}`.
- With `Accept: text/event-stream` it streams `ready`, then `receipt` and `item` events as questions finish (not in
  sheet order), then `record`, `budget`, `done`.
- Statuses: `approved` (approved answers), `policy` (built from a policy passage; needs sign-off), `review` (partial fit,
  or the approved answer conflicts with the policy it cites), `none` (nothing approved; `answer` is null), `error`.
- `adaptation.mode`: `verbatim`, `extract` (whole sentences of the approved text), `grounded` (an edit the judge found
  supported) or `reverted` (the edit added something; the approved text was used). `yes_no` is filled only when the
  approved answer gives the same Yes or No.

## Example: fill a sheet and save it (Python, `pip install httpx`)
```python
import base64, httpx, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
b64 = lambda p: base64.b64encode(open(p, "rb").read()).decode()
body = {"questionnaire": {"file": {"name": "buyer.xlsx", "b64": b64("buyer.xlsx")}},
        "library": {"files": [{"name": "approved-answers.csv", "b64": b64("approved-answers.csv")}],
                    "documents": [{"id": "POL-ISP", "title": "Information Security Policy", "text": open("pol-isp.txt").read()}]}}
r = httpx.post(f"{API}/questionnaire/answer", json=body, headers=H, timeout=900)
r.raise_for_status()
run = r.json()
for it in run["items"]:
    if it["status"] in ("none", "review", "error"):
        print(it["id"], it["status"], it["reason"])
x = httpx.post(f"{API}/questionnaire/export", json={"items": run["items"], "format": "xlsx", "record": run["record"]}, headers=H, timeout=60)
open("buyer-filled.xlsx", "wb").write(x.content)
```

## Verify the review record (`pip install cryptography`)
```python
import json, urllib.request
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
rec = run["record"]
pub = json.load(urllib.request.urlopen("https://api.decosa.ai/attest/signing-key"))["pubkey"]
assert rec["signer"] == pub
body = {k: v for k, v in rec.items() if k != "sig"}
msg = rec["v"].encode() + b"\n" + json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
Ed25519PublicKey.from_public_bytes(bytes.fromhex(pub)).verify(bytes.fromhex(rec["sig"]), msg)
```
Or `POST https://api.decosa.ai/questionnaire/verify` with `{"record": rec, "answers": [{"i", "answer"}]}`. The record holds
hashes, source ids and statuses, never text. Each id in `rec["receipts"]` resolves at `GET https://api.decosa.ai/receipts/{id}`.

## Honest limits
- A person reads the sheet before it is sent. The checks are model judgements, and they do not catch an answer that
  leaves out a qualifier. The eval numbers on the Stack tab come from a synthetic library.
- PDFs and Word files are not read: send their text as documents.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa security questionnaire answerer: run it yourself (containers)

You are setting up the Decosa questionnaire answerer on this machine, so our policies and approved answers never leave
it. It fills a buyer's security questionnaire from approved text only, checks every change against its source, and
signs a review record. Nothing is sent to Decosa's hosted API.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/security-questionnaire.zip (7 KB, 10 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py security-questionnaire` (the api image carries the same bundle under /app/rehearsal/security-questionnaire/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py security-questionnaire --bundle security-questionnaire.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the CSV questionnaire parses into four questions", "the security-policy question (GOV-01) fills from an approved answer", "the encryption question (CEK-01) fills from approved answers naming AES-256 and TLS 1.2"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). Also install the NVIDIA container toolkit and
   check `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`. One GPU with 32 GB or more.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `llm` service (Qwen3.8-27B on vLLM) and the `api` service. For the `api` service set
   `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b` and bind every port to
   127.0.0.1.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
   downloads about 20 GB of weights).
4. Check: `curl -fsS http://127.0.0.1:<PORT>/questionnaire/info` lists the statuses and prompt hashes;
   `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify our records.
5. Smoke test: get a token with `POST /demo/session {"vertical":"security-questionnaire"}`, fetch
   `GET /questionnaire/samples`, and send `samples[0].questionnaire` and `samples[0].library` to
   `POST /questionnaire/answer`. Expect most questions `approved`, TVM-01 and LOG-01 `review` (their approved answers
   conflict with the current policy), and FedRAMP, bug bounty and similar questions `none`. Then
   `POST /questionnaire/verify` with the record: `valid_signature` and `signed_by_this_server` must both be true.
6. Report back: the public key, the status counts, and how long the run took.

Off by default. Joining as a provider serves other people's requests on this GPU; never do it on a box that holds our
policies. If I ask for it later, follow the Provide page instead of improvising.

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/security-questionnaire-mac.md instead.