agentleFS
roselis-labroselis-lab/keel/.claude/skills/assess-genai-with-library/SKILL.md

assess-genai-with-library

Skill2 starsChanged 4 days agoApache-2.0View on GitHub

Use when assessing the GenAI/LLM security of a specific system, integration, agent, RAG, or feature ("assess security", "threat model", "security review", "risk assessment of an integration") and the in-house Keel threat-model MCP is available to draw on.

The file

Files
SKILL.md

Assessing a GenAI system against the threat library

Overview

The library is the methodology crystallized into a catalog of threats, each a harm (the consequence) resting on weaknesses at owned components, each reached across a surface (the channel whose content that component treats as trustworthy), driven by a source, with a reachability carve-out and linked mitigations. It gives you candidates and coverage, but you must reason FROM THE SYSTEM: the catalog is a floor, not a ceiling, and not a substitute for analysis.

REQUIRED, source of truth: run the assessment strictly by the assessing-genai-security methodology and follow it verbatim, all its steps, the data-sufficiency gate, the output format. Nothing here overrides or paraphrases it: it is calibrated. This skill only points to where the library plugs into its steps, and adds what a saved, reviewed report needs.

Two kinds of completeness, and a report shows both: every catalog threat class was considered (the threat search below), and every surface of this system was walked (the surface ledger). One without the other looks finished and is not.

Steps

  1. Note the time you started. Before anything else, record the current timestamp. It goes into the report as meta.started_at, and it is the one thing that cannot be reconstructed afterwards. An assessment that costs the specialist two hours is a different product from one that costs twenty minutes, and nobody remembers which it was a week later.
  2. Identify the system (before the methodology's step 1). Assessments are archived per system. Call list_reports and read the system_description of each system's most recent assessment (get_report). If one plausibly describes the system in front of you, propose the match and wait, do not assume it. A specialist with fifty systems will not remember the slug, and two similar agents are easy to confuse. On a confirmed match, read that report in full and assess by delta: what changed in the architecture since that date, which findings are affected, which are untouched. Start from the places it pinned rather than searching again: run keel recheck reports/<system-id>/<date>.yaml --repo <checkout> (--repo NAME=PATH per repository when its evidence names one), and read what it lists as moved or gone first. "In place" only says the quoted lines did not change, not that the finding still holds. Re-derive nothing that has not moved, but do re-check each carried-forward finding rather than copying it, because a control that closed a gap can also have been removed. Read its discarded list too: what it ruled out, by reachability or in review, stays ruled out unless you have a new fact, and then you name that fact in delta. On no match, this is a first assessment: pick a new system-id (lowercase, hyphenated, stable, it is a folder name forever) and leave delta_summary null.
  3. Build the surface ledger (inside the methodology's step 1). From the code and configuration, list every place something reaches this system: entry points (endpoints, chat, inboxes, webhooks), tools the model can call, data paths in and out (retrieval, memory, files, provider calls), and the files you read to establish them. Each goes into surfaces with where it is and the evidence you saw it in. Then call get_vocabulary and walk each surface's variants against the system: they name the concrete forms content arrives in (a calendar invite, a file name, an image the pipeline downscales, chat history the client sends back), what it can hide (HTML comments, invisible characters, a page served to the agent differently than to a person) and the routes output leaves by (an image the client auto-loads, a link the person clicks, a DNS lookup from a shell, an allowed service someone else owns). Each variant the system has gets its own row, whether what travels it is planted, stale or the model's own mistake; one the system lacks needs nothing. The ledger is done when every entry point in the code and every variant the system has holds a row, not when the obvious ones do. Fields: references/report.md.
  4. Search the catalog (in the methodology's threat search). Don't pull the whole catalog with all fields in one call, a full list_threats(brief=false, include=[all]) doesn't fit in one tool response. Query pattern: (1) a light index mcp__keel__list_threats(brief=false, include=["harm","weaknesses"]) for a first-pass pattern match (the weaknesses, cause + where + defect, are the recognition anchor); (2) the relevant candidates in one call, mcp__keel__list_threats(brief=false, ids=[...], include=["harm","source","weaknesses","reachability","mitigations"]), for source, reachability and linked mitigations (surface already comes with the weaknesses in step 1). Read each threat once and keep what it says in your notes; get_threat adds references, positioning and cited_by, which an assessment does not use and which double the size of every card left in context. This does NOT override the methodology's rule "search from the system, not from a catalog": the catalog is a floor. After matching, walk the harm classes (wrong-decision, data-integrity, data-exposed, code-execution, downtime, reputation-legal - take them from get_vocabulary rather than this line, which is a reminder and not the source) and check whether an asset is under threat that the catalog misses, analyze such a threat from scratch by the methodology. Then walk the ledger: every surface ends with findings, discards or paused branches that cross it, or with a written reason nothing reaches harm through it.
  5. Match the chain (in the methodology's source, harm and weakness steps). harm = the consequence class; source = who or what drives it, one catalog value per source the methodology's source step names (its injection is external-attacker arriving over a surface, since the model is only the channel there; the model as a source in its own right is model-mistake, model-overeager or model-own-goal); weaknesses = the architectural conditions (cause + where + defect), i.e. how the system is exploitable. Each weakness names the component it sits on (model / tool / downstream / memory / knowledge-base / identity-store) and, when something flows in, the surface it arrives through - check the system actually has that component, that the channel exists in this architecture, and that the condition holds there. A weakness with no surface is about the component's own authority, so it is reachable without anything crossing a boundary. Mind nature: a targeted weakness is an independent attack path (remove it and the attack fails); a secondary one only amplifies impact or likelihood, so it modulates severity, it is not itself the opening. The match is advisory, not a checklist: does the weakness fit THIS architecture.
  6. Decide applicability. After a match, apply reachability ("NOT applicable if…") on the UN-mitigated architecture. A carve-out that doesn't close it → the threat is live; carry it further down the methodology's chain. Missing a fact to decide → this is the methodology's data-sufficiency gate: look in the code and configuration first, ask for the access if you know where the fact is, otherwise record it in open_questions, put the candidate in paused, and wait for the answer. Never assess on an assumption, and never grade it now to fix later. The gate is symmetric: DROPPING a threat by taking a missing fact as "absent" (e.g. calling output inert text without confirming the render mode; assuming a tool is unreachable) is the same violation as confirming it on an assumption. No fact → ask, don't drop. Where checking is cheap and safe (a local run, a test against a fixture, no production credentials), reproduce the path and record it as test evidence: a reproduced finding is stronger than a read one, and the report shows which is which.
  7. Grade and price controls (in the methodology's risk and mitigation steps). Grade on Keel's three-level scale with the anchors in references/grading.md: open it for every grade. The linked mitigations came with the threats in step 4; each link's rationale says why that control addresses this threat's specific weakness, use it as the starting map, but verify the mapping against the real architecture rather than trusting the prose. Keep the controls applicable to this system. Mind each link's strength: a soft link only lowers likelihood (by the methodology's cross-cutting rule it is not an architectural control and does not finalize the threat); a gating link is an architectural control that blocks the threat. Then judge whether the control is actually in place in this deployment: mcp__keel__get_mitigation(id) and read its implementations, a recorded implementation, especially one the platform or surrounding infrastructure provides, means the control already covers this system and genuinely reduces the threat; an empty implementations list means it is only a recommendation, not yet present, so do not credit it as covering the system, verify its presence from the architecture instead. Read failure_behavior too: a control that fails open (lets the threat through when it fails) is materially weaker than one that fails closed, weigh that in the residual risk. A catalog control already says what it holds, where (locus) and how it is accepted (validation) on its card: read them, and write in the requirement only what is specific to this system. An ask with no card names the invariant it enforces, where it is enforced, and how to check it is done (references/report.md). To name the component that enforces it on this system, start from references/enforcement-points.md and confirm it in the code.
  8. Have every high finding refuted. Each finding graded high on severity goes to a reviewer who did not raise it: a fresh subagent with the brief in references/review.md, or the specialist. The reviewer tries to break the chain, not to agree with it, and also looks for surfaces the ledger missed. Record the verdict in the finding's review. A refuted finding moves to discarded with by: review and the reason; a weakened one is regraded; new surfaces go into the ledger and through steps 4 to 7.
  9. Polish (second to last step). Once the assessment is complete, polish the final assessment (part 2 of the output) through two skills via the Skill tool, in order: tighten-text (concision + de-bullet, tuned for security prose), then humanizer (remove AI-tells, natural expert voice). Both are substance-preserving and MUST NOT drop or alter risk levels, HARD/SOFT tags, GATE ITEMS / stated uncertainty, the delta, mitigations, or any domain specifics, they tighten wording and voice only. Keep the two-part structure and the analysis trail intact; don't polish the audit trail's reasoning away. Polish only once nothing is paused: an open question is answered before the polish, not after it.
  10. Write the report and hand back a link (last step). An assessment that lives only in this conversation is lost. Write it through the Keel MCP tools, create_report for the empty draft, then update_report with the parts as you finish them, filling every field by references/report.md. Write the report once, in Keel: no draft copy in a file, and no resending what is already saved. update_report takes only the items you add or change (a finding, its evidence, an answer), and the next pass sends only its own; save_report takes the whole document and is for rewriting it. Output tokens are the most expensive part of a run, and reprinting a report is where most of them went. The link is the deliverable, not a wall of YAML pasted back into chat. Do not write the YAML file directly: the tools check what a plain file write cannot, and a file written round the side of those checks lands broken and nobody finds out until someone opens it. When update_report or save_report returns open, the assessment is not done. Get the answers: ask the specialist, or, if you run as a subagent, return the questions to the session that started you and wait. Write the answer into the question, turn each paused branch into a finding or a discard, and send those items with update_report. A paused branch left waiting on an answered question is refused on save. Then hand back the link, using the host and port Keel is served on (keel up serves 127.0.0.1:8420 and prints the address; ui_port in keel/config.py holds the port):

    http://127.0.0.1:8420/reports/<system-id>/<YYYY-MM-DD>

    Say in one line what the reader will find there and what is left to do, e.g. "3 findings, 5 requirements, review the grades and finalize." Do not print the YAML. Where a deterministic check (a static rule, a configuration query, a test, a script) would confirm a finding and is cheap and safe to run here, run it before saving and record it as command or test evidence. Hand the link back as finished only when open is empty; until then what you hand back is the open questions.

The record is a draft, and stays one. The specialist corrects grades and wording, then finalizes it themselves in the UI. Finalizing is not exposed to you: signing off on someone else's judgment is not yours to do.

Assessing many systems. Give each system its own subagent and hand it the system, not your history: what to assess, where the code and configuration are, and the answers already known. Have it return the report link, its open list and a few lines on what it found, never the report itself. A subagent rereads its whole context on every step, so a context kept short is the cheapest thing in a long run; a subagent whose context passes half the window should hand its findings to a fresh one rather than go on.

Common mistakes (library-specific; methodological ones live in the methodology)

  • Dropping on an assumption, killing a threat by taking a missing fact as "absent" (e.g. calling output inert without confirming the render mode). A drop needs the same gate as a confirmation.
  • Catalog as a checklist, skipping reachability carve-outs → over-applying threats the system doesn't have.
  • Catalog as a ceiling, not walking harm coverage, missing a threat outside the catalog.
  • Classes without surfaces, every catalog threat considered but the ledger holds only the obvious entry points, so a fast run reads like a deep one.
  • Copying the prose of weaknesses/reachability instead of tying the wording to the specific system.
  • SOFT taken as a guarantee, a soft mitigation link does not close the threat.
  • Crediting an unimplemented control, a mitigation with no implementations recorded here is a recommendation, not evidence the threat is already covered in this deployment; confirm the control's presence from the architecture.
  • One cause written as four findings, the same root_cause under several harms with the same fix. Keep one finding per harm, as the model says, but give them the same root_cause so the report shows one fix closes them all.
  • A ruled-out threat coming back, re-raising what an earlier report discarded or refuted without naming the new fact.
  • No delta taken as no threat, dropping a threat because it existed before the integration. Mark it legacy, grade it and give it measures; it is only not counted against the integration.
  • Per-item grading of a set on intuition (flip-flop), judging each of a set of tools, endpoints or actions by gut, then flipping one verdict when challenged. When you grade a set, use the risk frame in references/grading.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.