Authoring Guide

A hunting tool, not a reference document

The instinctive way to build a playbook is to document a vulnerability: capture every component involved, every variant, every technique, and save it. The result looks thorough — and it never fires.

A reference document is something you consult after you already suspect a vulnerability. A hunting tool fires before you have consciously made the connection, because the conditions you have mapped already satisfy its trigger. Those are different goals, and they produce different playbooks.

A playbook's component requirements are not a description of a vulnerability. They are the minimum set of observable signals that tell the Nexus Engine "this playbook is now relevant to this target."

The detection path question

Before you assign a single component, answer this:

What would I need to observe in a target for this attack to become worth testing?

Not "what are all the components involved" — at what point in your reconnaissance does the playbook become relevant, and what observable signals mark that point?

Most playbooks need only two or three component types to define a meaningful trigger. The rest belongs in the playbook body. Forcing every type into the requirements doesn't make a playbook more rigorous — it makes it harder to trigger, slower to assign, and noisier.

The building blocks

Required is an AND gate

Required does not mean "this field must be filled in." Required means "this component must be confirmed and assigned before this playbook is considered applicable."

All required components together form the sufficient condition: the engine stays silent until every one is satisfied. This makes the choice of required components the most consequential decision in playbook design:

• Too few required conditions → the playbook fires on irrelevant targets. Noise.
• Too many → it can never fire in black-box hunting. Silence.

The goal is the minimum set that fires at the right time and not before.

Optional components shape confidence

An optional component does not gate the playbook — it weights the suggestion. Present raises confidence; absent lowers it. Use it for signal that matters but cannot be a hard requirement: a Technology that is disproportionately affected, or a Gadget that varies by application. Required components define when the playbook fires; optional components define how confidently.

Encode blind spots as required quirks

A required component-level quirk (CLQ) is not just a gate — it is a proactive prompt. When a playbook is partially satisfied and the only missing piece is a required CLQ, the engine turns it into a proactive prompt asking you to confirm that condition.

This lets you encode the things you know you would forget. If you always map a file upload that accepts archives and move on without checking whether the server extracts them, make "server-side archive extraction" a required CLQ — and never skip it again.

Categories

A category assignment replaces a specific component with a category-wide condition: instead of requiring "Login Form," require any Functionality in the Authentication category. One assignment covers every variant, including ones that don't exist yet.

The type is always locked by the slot: a category on a Functionality slot resolves against functionalities only. If any member of the category makes the playbook relevant, use a category assignment; if only a subset does, use the next tool.

Tags and category + tag

Tags live on components in the library and travel with them. A category + tag assignment requires both conditions simultaneously — the component must be in the category and carry the tag.

This is how you handle variance without multiplying playbooks. One playbook requiring File Types + #archive-file covers ZIP, TAR, JAR, and every future format you tag — no new playbook ever needed. If you find yourself writing near-identical playbooks that differ only by which component is involved, collapse them into one and let tags do the work.

The seven principles

Adapted from the Nimbus playbook design methodology:

1. Map the detection path, not the vulnerability. Requirements are trigger conditions. Exploitation steps, variants, and language nuance belong in the body.
2. Use required components as sequential filters. Each one should eliminate a meaningful subset of irrelevant targets. If removing it changes nothing, it isn't load-bearing.
3. Encode your blind spots as required CLQs. The engine will hold the playbook partially satisfied and keep asking until you confirm or rule out the condition.
4. Let context do its share. If a competent hunter would naturally observe and record it, don't systematize it.
5. Keep the trigger lean, push detail downstream. The body is for what to do after the playbook fires — never for what the engine needs to decide it should.
6. Use tags to absorb variance. One playbook tagged across all affected variants beats one playbook per variant.
7. Ask the minimum-components question last. Challenge every requirement: can I remove it and still not fire on irrelevant targets? If yes, remove it.

Case study: Zip Slip

Step 1 — the research. Zip Slip is directory traversal through archive extraction: it needs an upload that accepts archives, and server-side extraction of those archives.

Step 2 — the detection path question. What would I need to observe for Zip Slip to become worth testing?

1. A file upload — no upload surface, no attack. This is the broadest gate.
2. The upload accepts archives — an image-only upload has no exposure. Handled by a tag, not by naming every format.
3. The server extracts what was uploaded — storing archives isn't enough. This condition is invisible from the upload interface, which is exactly why it must be encoded as a required CLQ.

Java is meaningful context on top — disproportionately affected — but it is not part of the detection path, so it is optional.

Step 3 — the final playbook.

Required Components:

  [Functionality]
  File Upload  (Required)
    [CLV] File Types + #archive-file — Required
    [CLQ] server-side archive extraction — Required

  [Technology]
  Java — Optional (confidence signal)

Execution Steps (in the playbook body):
  1. Craft an archive whose filenames contain traversal sequences
  2. Upload it through the identified functionality
  3. Observe whether traversal paths are preserved server-side
  4. Attempt to overwrite a known file to confirm arbitrary write
  5. Chain to RCE by targeting files the server process will execute

Notice what is not there: no gadget naming the extraction library (varies by app, unconfirmable black-box), no vector naming the filename field (implicit in confirmed extraction), no quirk for missing path validation (that is what you are testing for). All of it is real, useful knowledge — none of it belongs in the trigger.

Before you finalize

• Is every required component observable during normal reconnaissance, without a dedicated investigation?
• Does each required component eliminate a meaningful subset of irrelevant targets?
• Is there any required component that can almost never be confirmed black-box?
• Is there a condition that is both necessary and easy to forget? Is it a required CLQ?
• Could two playbooks be collapsed into one with better tag usage?
• Is there anything in the requirements that a hunter would only need after deciding to run the playbook?

If those all hold, you have built a hunting tool.

The deeper principle

Nimbus is not a vulnerability database. It is a context engine. A database stores information and retrieves it when you query; a context engine observes the context you are building and surfaces relevant attack surface automatically.

For that to work, it needs to know the right conditions under which each playbook becomes relevant. Too broad — noise. Too narrow — silence. The precise middle ground is what this guide is about.

What's next

• Requirements — every assignment level and property in detail.
• Yields and Primitives — what playbooks produce, and how chains form.