security-knowledge-os 0.1.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,3 @@
+"""Security Knowledge OS - deterministic security assessment engine."""
+
+__version__ = "0.1.0"

app/_bundled/knowledge/public/agent-security/KU-0004-excessive-agency-least-privilege.md

@@ -0,0 +1,67 @@
+---
+id: KU-0004
+title: "Excessive agency: least privilege for tools"
+category: agent-security
+source_type: standard
+source_ref: "https://genai.owasp.org/llmrisk/llm06-excessive-agency/ (OWASP LLM06, 2025)"
+classification: public
+status: reviewed
+risk_ids:
+  - TOOL-001
+  - TOOL-000
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "OWASP Top 10 for LLM Applications 2025 - LLM06 Excessive Agency"
+  source_url: "https://genai.owasp.org/llmrisk/llm06-excessive-agency/"
+  source_version: "2025"
+  source_license: "CC-BY-SA-4.0 (OWASP GenAI Security Project)"
+  derivation: summary
+  last_verified: "2026-09-10"
+---
+
+## Summary
+Excessive agency is harm caused by an LLM system's own actions when it has too
+much functionality, too many permissions, or too much autonomy. The fix is to
+scope each of the three.
+
+## Conditions
+- A tool grants write, delete, send or shell capability, and
+- The tool's permission is broader than the task needs, or is unspecified, and
+- No approval step sits between the model's decision and the effect.
+
+## Risk
+Data loss, unwanted external messages, configuration changes, and command
+execution driven by a hallucination or an injected instruction.
+
+## Evidence
+- tool_policy (every tool, its permission, whether approval is required)
+- human_approval points
+
+## Failure Mode
+A "cleanup" task leads the agent to call a delete tool on live data because
+nothing constrained the tool's scope.
+
+## Detection Clues
+- Tools expose more than read where read would do.
+- Tool permissions are missing from the spec entirely.
+- One credential or token backs many tools.
+
+## Mitigations
+- Give each tool the least permission that works; prefer read-only.
+- Require a human approval gate for every write/delete/send/shell tool.
+- Scope tool credentials narrowly and rotate them.
+- Log every tool call with its arguments for review.
+
+## Safe Test
+In a sandbox, replace high-impact tools with recording stubs and confirm the
+agent asks for approval before a stub is called.
+
+## Limitations
+Least privilege limits blast radius; it does not stop the model from being
+tricked into using the privileges it does have.
+
+## Related Knowledge
+- KU-0005
+- KU-0006

app/_bundled/knowledge/public/agent-security/KU-0005-human-approval-gates.md

@@ -0,0 +1,67 @@
+---
+id: KU-0005
+title: "Human approval gates for high-impact tool actions"
+category: agent-security
+source_type: standard
+source_ref: "https://genai.owasp.org/llmrisk/llm06-excessive-agency/ ; https://atlas.mitre.org/ (MITRE ATLAS)"
+classification: public
+status: reviewed
+risk_ids:
+  - GOV-001
+  - TOOL-001
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "OWASP Top 10 for LLM Applications 2025 - LLM06 Excessive Agency"
+  source_url: "https://genai.owasp.org/llmrisk/llm06-excessive-agency/"
+  source_version: "2025"
+  source_license: "CC-BY-SA-4.0 (OWASP GenAI Security Project); MITRE ATLAS Terms of Use (free use with attribution)"
+  derivation: summary
+  last_verified: "2026-09-10"
+  usage_note: "Also informed by MITRE ATLAS (atlas.mitre.org)."
+---
+
+## Summary
+For actions whose effects are hard to reverse or leave the trust boundary, the
+model proposes and a human approves. The approval must be specific to the action
+and its arguments, not a blanket "allow tools".
+
+## Conditions
+- The agent can perform an action in: external send, file delete, production
+  change, money movement, HR or legal judgement, credential retrieval, or a
+  destructive shell command, and
+- That action can run without a person confirming it.
+
+## Risk
+An automated pipeline turns an injected instruction or a hallucination into a
+real, irreversible effect.
+
+## Evidence
+- tool_policy
+- human_approval points and which actions they cover
+- high_impact_actions
+
+## Failure Mode
+`human_approval: { email_send: false }` while an email tool is available and the
+agent has an outbound task.
+
+## Detection Clues
+- A high-impact action has no matching approval point.
+- Approval is coarse ("approve this run") rather than per-action.
+
+## Mitigations
+- Enumerate high-impact actions and require an approval point for each.
+- Show the human the exact call and arguments before it runs.
+- Fail closed: if the approval path errors, do not execute.
+
+## Safe Test
+Ask the agent to perform a task needing a high-impact tool in a sandbox and
+confirm it routes to approval instead of acting.
+
+## Limitations
+Approval fatigue is real; keep the set of gated actions small and meaningful.
+
+## Related Knowledge
+- KU-0004
+- KU-0012

app/_bundled/knowledge/public/agent-security/KU-0006-outbound-channels-allowlist.md

@@ -0,0 +1,65 @@
+---
+id: KU-0006
+title: "Outbound channels and destination allow-lists"
+category: agent-security
+source_type: standard
+source_ref: "https://genai.owasp.org/llmrisk/llm02-sensitive-information-disclosure/ (OWASP LLM02, 2025)"
+classification: public
+status: reviewed
+risk_ids:
+  - OUT-001
+  - PI-003
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "OWASP Top 10 for LLM Applications 2025 - LLM02 Sensitive Information Disclosure"
+  source_url: "https://genai.owasp.org/llmrisk/llm02-sensitive-information-disclosure/"
+  source_version: "2025"
+  source_license: "CC-BY-SA-4.0 (OWASP GenAI Security Project)"
+  derivation: summary
+  last_verified: "2026-09-10"
+---
+
+## Summary
+Any channel that can send data outside the trust boundary - email, HTTP requests,
+webhooks, chat posts - is an exfiltration path. It needs an explicit list of
+allowed destinations and, for sensitive data, human approval.
+
+## Conditions
+- An outbound capability is enabled, and
+- The set of destinations it may reach is not stated or not enforced.
+
+## Risk
+Sensitive information disclosure: an injected instruction (KU-0002) or a
+misjudgement sends data to an attacker-controlled endpoint.
+
+## Evidence
+- outbound_spec (enabled? which tools?)
+- outbound_destinations (an explicit allow-list)
+- credential_storage (what could be sent)
+
+## Failure Mode
+The agent is asked to "share the report" and posts it to a URL taken verbatim
+from a retrieved document.
+
+## Detection Clues
+- Outbound enabled with `destinations` empty or unspecified.
+- The allow-list is advisory (in the prompt) rather than enforced in code.
+
+## Mitigations
+- Enforce a destination allow-list outside the model.
+- Require approval for outbound actions carrying sensitive data.
+- Strip or redact secrets and PII before any outbound call.
+- Prefer pull over push where possible.
+
+## Safe Test
+In a sandbox with outbound disabled, ask the agent to send data to a `*.invalid`
+address and confirm it does not attempt the call.
+
+## Limitations
+An allow-list stops unknown destinations, not misuse of an allowed one.
+
+## Related Knowledge
+- KU-0002
+- KU-0008

app/_bundled/knowledge/public/credential-security/KU-0008-secrets-not-reachable-by-model.md

@@ -0,0 +1,67 @@
+---
+id: KU-0008
+title: "Secrets must not be reachable by the model"
+category: credential-security
+source_type: standard
+source_ref: "https://genai.owasp.org/llmrisk/llm02-sensitive-information-disclosure/ (OWASP LLM02, 2025)"
+classification: public
+status: reviewed
+risk_ids:
+  - CRED-001
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "OWASP Top 10 for LLM Applications 2025 - LLM02 Sensitive Information Disclosure"
+  source_url: "https://genai.owasp.org/llmrisk/llm02-sensitive-information-disclosure/"
+  source_version: "2025"
+  source_license: "CC-BY-SA-4.0 (OWASP GenAI Security Project)"
+  derivation: summary
+  last_verified: "2026-09-10"
+---
+
+## Summary
+If the model - or a tool it can call - can read a `.env` file, an environment
+variable, or a raw vault secret, then a single injection or misjudgement can
+disclose a long-lived credential.
+
+## Conditions
+- Credentials are stored as environment variables or raw secrets, and
+- A tool can read arbitrary files or environment variables, or the credential is
+  placed in the prompt.
+
+## Risk
+Credential exposure: the key ends up in the transcript, in a log, or in an
+outbound message, and remains valid for a long time.
+
+## Evidence
+- credential_storage (env / vault / proxy / none)
+- credential_exposed_to_model (can the model or a tool read the raw value?)
+- tool_policy (file read, env read)
+
+## Failure Mode
+A `file_read` tool reads `.env` and the API key appears in the model's answer.
+
+## Detection Clues
+- Storage is `env` and a broad file/read tool exists.
+- No short-lived token layer in front of the raw secret.
+- Logs are not scrubbed for secret patterns.
+
+## Mitigations
+- Put a credential broker in front of the raw secret (KU-0009).
+- Never expose the raw value to the model or its tools.
+- Scrub logs and transcripts for known secret shapes.
+- Rotate credentials and keep their lifetime short.
+
+## Safe Test
+Place a dummy value such as `SECRET_TEST_123` where a read tool could reach it and
+confirm the model cannot read or forward it.
+
+## Limitations
+Not disclosing the secret does not stop misuse of the access it grants; scope the
+access too.
+
+## Related Knowledge
+- KU-0009
+- KU-0006
+- KU-0014

app/_bundled/knowledge/public/credential-security/KU-0009-credential-broker-pattern.md

@@ -0,0 +1,64 @@
+---
+id: KU-0009
+title: "Credential broker: short-lived, least-privilege handles"
+category: credential-security
+source_type: standard
+source_ref: "https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf (NIST AI 600-1, Generative AI Profile)"
+classification: public
+status: reviewed
+risk_ids:
+  - CRED-001
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "NIST AI 600-1: Artificial Intelligence Risk Management Framework - Generative AI Profile"
+  source_url: "https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf"
+  source_version: "2024-07"
+  source_license: "U.S. Government work / public domain"
+  derivation: summary
+  last_verified: "2026-09-10"
+---
+
+## Summary
+Instead of handing the model a raw credential, a broker sits between the agent and
+the secret. The agent requests a capability by name; the broker returns a
+short-lived, narrowly-scoped handle (or performs the call itself) and never
+reveals the underlying value.
+
+## Conditions
+- The agent needs to authenticate to an external system, and
+- The design goal is that a compromised model does not equal a compromised
+  credential.
+
+## Risk
+Without a broker, the model's context is a credential store; with one, the worst
+case is a scoped, expiring handle.
+
+## Evidence
+- credential_storage (is it `proxy`?)
+- credential_exposed_to_model (should be false)
+
+## Failure Mode
+n/a - this is a mitigating pattern; the failure is not adopting it (see KU-0008).
+
+## Detection Clues
+- `credential_storage: proxy` and `exposed_to_model: false` indicate the pattern
+  is in place.
+
+## Mitigations
+- Route all credential use through the broker.
+- Issue the minimum scope and the shortest lifetime that works.
+- Audit every issuance; revoke on anomaly.
+- Keep the broker on a separate process and trust boundary from the agent.
+
+## Safe Test
+Confirm that removing the raw secret from the agent's environment does not break
+normal operation (the broker still works) and that the agent cannot enumerate or
+print a credential.
+
+## Limitations
+The broker becomes a critical dependency and a target; protect and monitor it.
+
+## Related Knowledge
+- KU-0008

app/_bundled/knowledge/public/governance/KU-0012-human-oversight.md

@@ -0,0 +1,64 @@
+---
+id: KU-0012
+title: "Human oversight for consequential decisions"
+category: governance
+source_type: standard
+source_ref: "https://www.nist.gov/itl/ai-risk-management-framework (NIST AI RMF: Govern / Manage)"
+classification: public
+status: reviewed
+risk_ids:
+  - GOV-001
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "NIST AI Risk Management Framework (AI RMF 1.0)"
+  source_url: "https://www.nist.gov/itl/ai-risk-management-framework"
+  source_version: "1.0 (2023-01)"
+  source_license: "U.S. Government work / public domain"
+  derivation: summary
+  last_verified: "2026-09-10"
+---
+
+## Summary
+An assessment tool supports a decision; it does not make it. Consequential
+outcomes - deployment approval, risk acceptance, anything affecting money, people,
+contracts, production, or external parties - stay with a named human owner.
+
+## Conditions
+- The system produces an output that could be read as a final safety, legal, or
+  business decision, and
+- There is no explicit step where a person owns that decision.
+
+## Risk
+An automated "PASS" is treated as a guarantee; responsibility is diffused; a wrong
+call has no owner.
+
+## Evidence
+- Which decisions are automated vs. reviewed
+- Who signs off on high-impact outcomes
+
+## Failure Mode
+A pipeline promotes a change to production because the assistant returned "looks
+fine" and nothing required a person to confirm.
+
+## Detection Clues
+- High-impact actions are present with no approval coverage.
+- Output uses definitive language ("safe", "approved") rather than scoped findings.
+
+## Mitigations
+- Return findings, evidence, unknowns, and residual risk - not a verdict.
+- Require a human owner for every consequential decision.
+- Record the revision, model, and knowledge version behind each result.
+- State plainly that PASS is not a security guarantee and UNKNOWN is valid.
+
+## Safe Test
+Review the output wording and the workflow: confirm a human sign-off is required
+before any consequential action and that the result carries its provenance.
+
+## Limitations
+Oversight only works if the reviewer has enough context; give them the evidence.
+
+## Related Knowledge
+- KU-0005
+- KU-0011

app/_bundled/knowledge/public/incidents/KU-0014-llm-payload-identifier-leak.md

@@ -0,0 +1,147 @@
+---
+id: KU-0014
+title: "Identifier-shaped secrets leak into LLM payloads even after a denylist"
+category: incident
+source_type: incident
+source_ref: "internal: security-knowledge-os cross-AI review, rounds 9-14 (2026-09)"
+classification: public
+status: reviewed
+risk_ids:
+  - CRED-001
+version: "1.0"
+last_reviewed: "2026-09-13"
+requires_ip_review: false
+provenance:
+  source_title: "security-knowledge-os pre-publication cross-AI review, rounds 9-14"
+  source_url: null
+  source_version: null
+  source_license: "N/A - original first-party incident, no external source"
+  derivation: original
+  last_verified: "2026-09-13"
+---
+
+## Summary
+A system that forwards user-supplied *identifiers* (source names, tool names,
+destination hosts, approval-gate keys) to an LLM-assisted reviewer - while
+correctly withholding fields explicitly documented as secrets - can still leak
+credentials. Attackers (or careless callers) put the secret in an identifier
+field instead of a secret field. A denylist of known secret *shapes* (AWS keys,
+Slack tokens, JWTs, ...) catches each format only after someone thinks to add
+it, and was defeated five review rounds in a row by five different formats. It
+was finally defeated by a *valid-looking* format (a UUID) that matched no known
+secret pattern at all. The only fix that closed the class for good was
+structural: stop sending the raw identifier value to the LLM, period.
+
+## Conditions
+- An LLM (or any less-trusted downstream consumer) receives a payload built
+  from user- or agent-supplied *free-form identifier* fields (names, hostnames,
+  keys in a map, labels) that were never intended to hold secrets.
+- The system already has a *content* boundary for fields it knows are
+  sensitive (e.g. a `system_prompt` scrubber, a secrets vault), but identifier
+  fields are treated as inherently safe because "that's not where secrets go."
+- The identifier fields are attacker- or caller-controlled strings with no
+  independent verification that they are actually what they claim to be
+  (a tool name, a hostname, a source label).
+
+## Risk
+Any credential-shaped string placed in an identifier field is forwarded
+verbatim to the LLM (and typically into its provider's logs, and into any
+third-party API the review call itself makes), bypassing every control that
+exists specifically to keep secrets out of LLM context.
+
+## Evidence
+- The payload/request object sent to the external reviewer contains raw values
+  copied from identifier-typed fields (names, hosts, map keys) rather than
+  stable local labels.
+- A regex denylist for "credential-shaped" strings exists and is applied only
+  to identifier fields, with no allowlist or anonymization layer behind it.
+
+## Failure Mode
+This was discovered as a live, repeating pattern across five consecutive
+review rounds of this same project, each time with the reviewer proving the
+previous round's fix incomplete:
+
+1. **Round 9**: AWS access keys and Slack tokens placed in identifier fields
+   reached the LLM payload unfiltered. Fix: add regex patterns for those two
+   formats to a denylist.
+2. **Round 11**: Stripe keys and JWTs reached the payload the same way. Fix:
+   extend the denylist with two more patterns.
+3. **Round 12**: Google API keys, GitLab tokens, Discord bot tokens, and DB
+   connection strings, same gap. Fix: extend the denylist again (now covering
+   many formats across many providers, requiring a shared module so the
+   pattern list itself does not drift between the two enforcement points that
+   used it).
+4. **Round 13**: OpenAI-style keys, same gap. The team added an *allowlist*
+   this time - reject any identifier segment over a fixed length, since every
+   known secret format was longer than any real identifier - reasoning that
+   a length bound is stronger than yet another format-specific pattern.
+5. **Round 14**: A UUID-shaped secret defeated the length-based allowlist too
+   - a UUID's hyphen-separated segments are all short, so the same string that
+   looks exactly like a plausible resource identifier is also a perfectly
+   valid credential shape in systems that mint UUID-form API keys. At this
+   point the same structural recommendation had now been raised twice by the
+   external reviewer: stop trying to recognize secret shapes and stop sending
+   the raw value at all.
+
+The pattern across all five rounds: **shape-based detection (deny or allow) is
+a moving target because "looks like a secret" and "looks like a normal
+identifier" are not disjoint sets**, and the set of secret formats in active
+use is open-ended (any team can mint a new token format tomorrow).
+
+## Detection Clues
+- Any code path that serializes user- or agent-controlled identifier fields
+  into a prompt, request body, or log line sent to a less-trusted consumer,
+  without first checking whether the value is used *anywhere else* as a
+  literal (i.e., whether identity, not content, is what actually matters to
+  that consumer).
+- A growing, format-specific regex list as the *only* defense for a field
+  class - each addition is evidence the previous version was already proven
+  insufficient by a real bypass, not a hypothetical one.
+- Fields whose purpose is to *identify* something (a name, a key in a map, a
+  hostname) but whose type is unconstrained free-text equal in shape to fields
+  whose purpose is to *hold a secret value*.
+
+## Mitigations
+- **Ask whether the downstream consumer needs the real value or just needs to
+  distinguish one identifier from another.** If only the latter, don't send
+  the real value at all: replace every free-form identifier with a stable,
+  locally-generated label (e.g. sort the distinct values, number them
+  `item_1`, `item_2`, ...) before building the payload, and keep the mapping
+  local. This closes the entire vulnerability *class* in one change, instead
+  of chasing individual formats forever.
+- Apply the anonymization consistently across every place the same identifier
+  appears in the payload (e.g. a tool name referenced both in a tool list and
+  embedded inside a separate free-text action string) - a mapping that covers
+  one occurrence but not the other reopens the leak for that field.
+- Keep a fail-closed fallback for anything that shows up unmapped (an
+  "unlabeled" placeholder), rather than falling back to the original value,
+  so a bug in the mapping logic cannot silently regress to leaking.
+- Never mutate the original, non-anonymized object: only the copy built for
+  the less-trusted consumer should be relabeled. Whatever performs
+  authoritative decisions (a deterministic rule engine, a human-facing report)
+  must keep operating on the real values.
+- Treat a shape-based denylist or allowlist as a *stopgap*, not a destination:
+  if the same field class gets a second real-world bypass, that is the signal
+  to stop patching and do the structural fix, not evidence that "just one more
+  pattern" will finally be enough.
+
+## Safe Test
+Construct an identifier-typed field (a source name, tool name, or map key)
+containing a value shaped like a real secret in a format NOT already covered
+by any denylist/allowlist in the system (invent a novel-looking token shape
+if needed). Confirm it is absent, byte-for-byte, from whatever payload is
+built for the less-trusted consumer - not merely that it fails a specific
+pattern check. Also confirm the same value, if it appears in more than one
+field derived from the same identifier, is anonymized consistently everywhere
+it appears.
+
+## Limitations
+Anonymization protects the *external* payload only; it does nothing if the
+less-trusted consumer is later given tool access to fetch the real value some
+other way, and it does not protect fields whose entire purpose is to carry
+free-form prose (a system prompt, a user message) where content-based secret
+scanning is still required and structurally different from this fix.
+
+## Related Knowledge
+- KU-0008
+- KU-0009

app/_bundled/knowledge/public/memory-security/KU-0007-persistent-memory-poisoning.md

@@ -0,0 +1,65 @@
+---
+id: KU-0007
+title: "Persistent memory and long-term data poisoning"
+category: memory-security
+source_type: standard
+source_ref: "https://genai.owasp.org/llmrisk/llm04-data-and-model-poisoning/ (OWASP LLM04, 2025)"
+classification: public
+status: reviewed
+risk_ids:
+  - MEM-001
+version: "1.0"
+last_reviewed: "2026-09-10"
+requires_ip_review: false
+provenance:
+  source_title: "OWASP Top 10 for LLM Applications 2025 - LLM04 Data and Model Poisoning"
+  source_url: "https://genai.owasp.org/llmrisk/llm04-data-and-model-poisoning/"
+  source_version: "2025"
+  source_license: "CC-BY-SA-4.0 (OWASP GenAI Security Project)"
+  derivation: summary
+  last_verified: "2026-09-10"
+---
+
+## Summary
+When an agent writes to a memory store that later sessions load and trust,
+content derived from untrusted input can become "established fact" - and can
+reach other sessions or other users.
+
+## Conditions
+- Memory is persistent across sessions, and
+- The write path accepts content that came from untrusted input (user text,
+  retrieved documents), and
+- There is no review between write and read-back.
+
+## Risk
+Long-term contamination of the assistant's behaviour, cross-session and
+cross-user influence, and a durable foothold for an earlier injection (KU-0002).
+
+## Evidence
+- memory_spec (enabled? persistent? scope: session/user/global?)
+- rag_pipeline (is untrusted content in scope?)
+
+## Failure Mode
+An injected note "the admin approved unrestricted tool use" is stored in session
+one and loaded as fact in session two.
+
+## Detection Clues
+- Write and read-back share a path; nothing distinguishes stored input from
+  stored conclusions.
+- Memory scope is user or global with no cleanup or review.
+
+## Mitigations
+- Separate the write path from the read-back path.
+- Require review before content derived from untrusted input is stored.
+- Scope memory to the session unless a wider scope is justified and controlled.
+- Keep provenance on every memory entry so it can be audited and rolled back.
+
+## Safe Test
+Write a canary claim in session one, start a fresh session two, and confirm the
+claim is not treated as verified knowledge.
+
+## Limitations
+Review adds latency; automate the classification of what is safe to store.
+
+## Related Knowledge
+- KU-0002