# worst-practices submission API — LLM researcher guide

You are reading this because a human pointed you at a GitHub URL and asked you
to find dangerous flags in it. This file tells you what "dangerous" means here,
how to format findings, and where to send them.

Fetch once, cache in context. Everything you need is below.

## What this database is

Self-inflicted security footguns. Flags a user *voluntarily types* that weaken
their own security. NOT attacker-controlled config files — that's a different
database. The question is always: "if I type this, what did I just do to
myself?"

Examples of what belongs here:
  curl --insecure              → you just disabled TLS verification
  docker run --privileged      → you just gave the container the host
  gpg --allow-weak-key-sigs    → you just accepted SHA-1 signatures
  pip install --break-system-packages  → you just overrode the safety rail

Examples of what does NOT belong here:
  rm -rf /                     → destructive, not a security footgun
  --verbose                    → noisy, not dangerous
  --force (most tools)         → usually just overwrites a file — only flag it
                                  if it bypasses a SECURITY check specifically
  any flag where the danger is "attacker put this in a config file" — wrong db

## Research workflow

Given a GitHub URL like https://github.com/owner/tool:

1. Fetch README.md, docs/, and the CLI --help output if you can run the tool.
   For man pages: `man <tool>` or fetch from manpages.debian.org.

2. Grep for the signal words. These are the phrases maintainers use when they
   know a flag is dangerous:
     insecure   unsafe   no-verify   skip-verify   disable-check
     allow-weak trust-all no-sandbox dangerously   at-your-own-risk
     bypass     ignore-   --yes (when it skips a security prompt)

3. For each hit, read the surrounding doc text. Ask:
   - Does this disable TLS/cert/signature verification?     → high
   - Does this disable a sandbox/isolation boundary?        → critical
   - Does this grant a capability the tool normally withholds? → varies
   - Does this suppress a security warning but not behavior? → skip it
   - Is "dangerous" here just "you might lose data"?        → skip it

4. Format each real finding as a rule (schema below). One rule per flag.

5. POST to /submit. You'll get 202 + `"state": "untriaged"`. Done.

Don't submit things you're unsure about. We'd rather have 3 solid rules than
30 maybes. Our triage rejects low-quality submissions and the rejection is
permanent (same rule ID won't be reconsidered).

## Severity rubric

  critical  direct path to RCE or full isolation bypass
            --privileged, --no-sandbox, --dangerously-skip-permissions
  high      defeats an auth/crypto/integrity check
            --insecure, --no-verify-ssl, sslVerify=false, --allow-unsigned
  medium    weakens a defense-in-depth layer
            --no-verify (git hooks), umask 000, --allow-root
  low       hygiene / deprecated-and-risky
            --allow-weak-digest, --legacy

When unsure, pick `low`. Triage will bump it if warranted.

## Rule schema

POST body wraps the rule in an envelope:

  {
    "tool": "docker",                        ← lowercase, matches argv[0]
    "submitter": "claude-cli@yourhost",      ← free-form, for attribution
    "source_url": "https://github.com/...",  ← where you found it (optional)
    "rule": {
      "id": "docker-privileged",             ← tool-flagname slug, globally unique
      "surface": "flag",                     ← flag | env | config
      "severity": "critical",
      "match": {
        "kind": "substring",                 ← substring | regex
        "value": "--privileged",
        "anchor": "docker"                   ← argv[0] this must appear after
      },
      "message": "docker --privileged gives the container ~all host capabilities",
      "why": "Disables seccomp, AppArmor, and the capability bounding set. Container can load kernel modules, access all devices, and trivially escape to the host. There is almost never a reason to use this outside of running docker-in-docker for CI.",
      "safe": "Use --cap-add for the specific capability you need. For device access use --device. For docker-in-docker, mount the socket (-v /var/run/docker.sock) instead.",
      "refs": [
        "https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities"
      ]
    }
  }

Field constraints (enforced server-side, submit will 422 on violation):
  id        ^[a-z0-9][a-z0-9-]*$   — pick {tool}-{flag-without-dashes}
  surface   flag | env | config
  severity  critical | high | medium | low
  match.kind  substring | regex | json-path | key-value
  message   ≤120 chars, one line, no trailing period
  why       1-3 sentences — THIS is what convinces triage. Be specific about
            the attack, not just "this is insecure"
  safe      what to do instead — optional but submissions with a good `safe`
            field get accepted much faster
  refs      URLs to official docs / CVEs / blog posts — optional, array

For env vars (surface=env), match.value is the VAR_NAME and match.kind is
usually "regex" matching `VAR_NAME=dangerous-value`.

Full JSON schema available at GET /schema if you want to self-validate.

## Submitting

  curl -sS -X POST {API_BASE}/submit \
    -H "Authorization: Bearer $WP_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d @rule.json

Responses:
  202  accepted, queued for triage — body has `"id"` and `"queued_at"`
  400  malformed envelope (bad tool name, missing rule, bad JSON)
  401  missing/wrong token
  422  rule failed schema validation — body has `"details": [errors]`
  503  server misconfigured (no token set) — not your fault

The token comes from the human who pointed you here. If they didn't give you
one, ask them.

## Batch submissions

One POST per rule. If you found 5 dangerous flags in one tool, that's 5 POSTs.
The `tool` field groups them server-side.

If you're about to submit more than ~10 rules for a single tool, stop. Either
the tool is unusually dangerous (possible — submit them) or your filter is too
loose (more likely — re-read the "what does NOT belong here" list).

## What happens after you submit

Your rule lands in an untriaged queue. It is NOT published, NOT visible on the
site, NOT in the scanner ruleset. A triage pass (human + LLM) reviews it:
  - accept  → promoted to rules/<tool>/, appears on site at next build
  - reject  → logged, same ID never reconsidered
  - edit    → we keep your finding but rewrite message/why/severity

You won't be notified either way. This is fire-and-forget.

## One-shot example for your human

They can paste this into a Claude CLI session:

  Read {API_BASE}/llm.txt. Then investigate https://github.com/example/sometool
  for dangerous CLI flags per the criteria in that file. For each real finding,
  POST it to the submit endpoint. My token is in $WP_API_TOKEN.

That's the whole integration.