yellow.git


yellow

~ opinionated web scanning pipeline for pentesters in a hurry
git clone https://github.com/djnnvx/yellow.git
log | files | refs | archive | README | LICENSE

SKILL.md (5658B)

      1 ---
      2 name: run-yellow
      3 description: Run the yellow recon pipeline against a target. Discovers the binary's actual subcommands and flags at runtime, asks which modules to enable, then runs the chain stage by stage. Use when asked to run yellow, kick off recon, or scan a target with this tool.
      4 allowed-tools: Bash(yellow*), Bash(./yellow*), Bash(command -v *), Bash(test *), Bash(ls *), Bash(cat *), Bash(wc *), Bash(head *), Bash(find *), Bash(git rev-parse*), AskUserQuestion, Read
      5 ---
      6 
      7 You run the `yellow` recon pipeline one stage at a time, so the user sees output
      8 and can stop between stages.
      9 
     10 **Never hardcode what yellow can do.** Modules and flags change every release.
     11 Discover them from `--help` at runtime and build your questions from what you
     12 actually find. If this file names a flag that no longer exists, `--help` wins.
     13 
     14 ## 0. Resolve the binary
     15 
     16 A stale binary is the single most common way to waste a run. Do this first:
     17 
     18 ```bash
     19 command -v yellow
     20 git rev-parse --show-toplevel 2>/dev/null
     21 ```
     22 
     23 If the working directory is inside a yellow checkout, prefer a freshly built
     24 `./yellow` over whatever is on PATH, and say which one you picked. Check for
     25 staleness before trusting either:
     26 
     27 ```bash
     28 ls -la --time-style=+%Y-%m-%d\ %H:%M "$(command -v yellow)" 2>/dev/null
     29 find . -name '*.go' -newer "$(command -v yellow)" 2>/dev/null | head -3
     30 ```
     31 
     32 If any source file is newer than the binary, tell the user it is stale and offer
     33 to `make` before running. Do not silently scan with an old build.
     34 
     35 If no binary exists anywhere, stop and say so.
     36 
     37 ## 1. Discover capabilities
     38 
     39 ```bash
     40 yellow --help
     41 ```
     42 
     43 Parse the `Available Commands:` block. Ignore cobra's built-ins (`completion`,
     44 `help`). Everything else is a real stage.
     45 
     46 Then, for each subcommand you intend to offer:
     47 
     48 ```bash
     49 yellow <subcommand> --help
     50 ```
     51 
     52 Read the flags off that output. That is the source of truth for:
     53 
     54 - which optional modules exist and whether each is opt-in (`--foo`) or
     55   on-by-default with an opt-out (`--no-foo`)
     56 - tunables (depth, duration, caps, ports, wordlist, rate limit, proxy)
     57 - whether a dry-run flag exists
     58 
     59 Note anything a flag's help text warns about (large downloads, extra requests,
     60 required API keys) and surface it in the question you build from it.
     61 
     62 Every invocation prints an ASCII banner first, and it contains a `--------`
     63 run that a naive flag grep will pick up as a flag. Read the `Flags:` block
     64 rather than grepping the whole output for leading dashes.
     65 
     66 ## 2. Confirm scope
     67 
     68 The target is a **bare domain or IP**: no scheme, no trailing path. It is used
     69 both as the loot directory name and the scan target, so anything else breaks the
     70 downstream paths.
     71 
     72 If the user gave no target, ask. Then confirm once that it is in scope for an
     73 authorized engagement, because the osint and scan stages touch it directly. One
     74 confirmation up front is enough; do not re-ask per stage.
     75 
     76 The loot tree is created in the current working directory. If that is a git
     77 repo, say so and offer to run somewhere else rather than dropping a loot tree
     78 into their source.
     79 
     80 ## 3. Ask what to run
     81 
     82 Use `AskUserQuestion`, with options built from what step 1 actually found. Do
     83 not offer a module that is not in the help output. Typical shape:
     84 
     85 - **Stages**: which of the discovered subcommands to run, and in what order.
     86   The usual chain is tree, then osint, then prune, then scan, because each
     87   consumes the previous one's output.
     88 - **Optional scan modules**: one multi-select built from the opt-in flags you
     89   discovered. Put the cost in each description (slow, loud, downloads N MB,
     90   needs a wordlist, extra request per URL).
     91 - **Default-on modules**: if you found `--no-*` flags, ask whether to disable
     92   any. Mention what is lost, since these are usually on for a reason.
     93 - **Tunables**: only ask when the default is likely wrong for this target, for
     94   example a crawl budget on a large site.
     95 
     96 Skip the questions entirely if the user already said exactly what they want
     97 ("just osint", "no port scan", "full chain, nuclei on"). Honour that directly.
     98 
     99 ## 4. Run the chain
    100 
    101 Run stages in order. Stop if one fails. Between stages, verify the next stage's
    102 input actually exists and is non-empty:
    103 
    104 ```bash
    105 wc -l <the file the next stage reads>
    106 ```
    107 
    108 If an input is missing or empty, stop and say so rather than running a stage
    109 that cannot work. This matters most when the user asked for a subset: prune
    110 needs a domain list from a prior osint run, and scan needs prune's output.
    111 
    112 **Long stages go in the background.** osint and scan take minutes. Launch them
    113 with Bash `run_in_background: true` so the session stays responsive, and wait
    114 for the completion notification instead of polling.
    115 
    116 Do not pipe a backgrounded stage through `tail`, `head` or `grep`. Those buffer,
    117 so you get nothing until the process exits and you lose all progress visibility.
    118 Write the raw output and filter it when you read it.
    119 
    120 Where output lands depends on the `-d` you pass, and stages differ in whether
    121 they expect the loot root or a subdirectory. Check the actual paths on disk
    122 after the first stage rather than assuming, then feed those exact paths onward.
    123 
    124 ## 5. Report
    125 
    126 Point the user at the real artifacts. List what was written rather than
    127 describing it from memory:
    128 
    129 ```bash
    130 find <loot dir> -type f -newer <marker> | head -40
    131 ```
    132 
    133 Report honestly. Zero findings is a valid result and should be stated plainly.
    134 If a module self-skipped for a missing API key, say which and why. If a stage
    135 was capped or truncated, say what was dropped.
    136 
    137 Several outputs contain live credentials or client data. Treat the loot tree
    138 accordingly and never paste secret values into a summary that might be shared.