From a5531af9b7f08d8cbcb8c9819192818374cfbddb Mon Sep 17 00:00:00 2001 From: Jean Paul Elisa NIYOKWIZERWA <140616733+Ndevu12@users.noreply.github.com> Date: Mon, 17 Aug 2026 21:36:20 +0200 Subject: [PATCH] docs: say where the report goes when a scan is too big for the terminal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A large sweep stops printing per-finding detail and writes the full report to a file instead. The reference said only that a path is printed on stderr — not where the file lands, how long it lasts, or that what it contains differs from what was on screen. So a reader who scrolled past that line had no way to find the report again, and no reason to expect the copy on disk to be redacted when the terminal's was not. Now stated: the bundle goes to `-d DIR` when you gave one and to a `sab-report-…` temporary directory otherwise; both `latest.md` and `latest.json` are written; the evidence there is redacted, as in any artifact on disk; `saw` never deletes the temporary copy, so it survives at the operating system's discretion; and `--json` turns the spill off because that payload already carries everything. Each of those was read off the code rather than the previous docs. Closes #1471 --- CHANGELOG.md | 6 ++++++ docs/reference/cli/scan.md | 6 ++++-- docs/reference/cli/sinks.md | 22 ++++++++++++++++++++++ 3 files changed, 32 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e268adb9..3828644f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,12 @@ reader, not the mechanism or the weakness it closed. ## [Unreleased] +### Added +- **Documented where the report goes when a scan is too large for the terminal.** A big sweep prints + a summary and writes the full per-finding report to a file; the reference now says where that file + lands with and without `-d`, that its evidence is redacted like any copy on disk, and that a + temporary one is left for your operating system to clear rather than deleted by `saw`. + ### Added - **The documentation is now published as a searchable, versioned site** at , with light and dark themes. Because `saw` ships pinned diff --git a/docs/reference/cli/scan.md b/docs/reference/cli/scan.md index 84b6ded4..03388a8f 100644 --- a/docs/reference/cli/scan.md +++ b/docs/reference/cli/scan.md @@ -38,5 +38,7 @@ saw scan -d /tmp/saw-reports # opt-in redacted latest.json + latest ``` On a terminal, a long sweep streams each target as it completes. A large sweep keeps the terminal to -a bounded dashboard and moves per-finding evidence into the written report, whose path is printed on -stderr — nothing is lost to scrollback, and you are never dropped into a pager. +a bounded dashboard and moves per-finding evidence into a written report, whose path is printed on +stderr — nothing is lost to scrollback, and you are never dropped into a pager. See +[the report a long scan writes for you](sinks.md#the-report-a-long-scan-writes-for-you) for where +that file lands and how long it survives. diff --git a/docs/reference/cli/sinks.md b/docs/reference/cli/sinks.md index 2aea7df6..e4e53637 100644 --- a/docs/reference/cli/sinks.md +++ b/docs/reference/cli/sinks.md @@ -11,3 +11,25 @@ so a report on disk can never re-distribute a live payload. | SARIF | `--sarif FILE` | redacted | `FILE`, for GitHub code scanning | | Alert | `--alert` | evidence-free | GitHub issue + Slack | | Reports dir | `-d DIR` | redacted | `DIR/latest.{json,md}` | + +## The report a long scan writes for you + +A scan whose result is too large for a terminal — many repositories, or a lot of findings and +advisories between them — stops printing per-finding detail and shows the summary table only. The +full report is written to a file instead, so nothing is lost to scrollback, and the path is printed +on stderr in a ruled block (clickable when your terminal supports it). + +Where it lands: + +| You passed | Written to | +| --- | --- | +| `-d DIR` | `DIR/latest.md` and `DIR/latest.json` | +| nothing | a fresh temporary directory named `sab-report-…`, printed with the report | + +Two things worth knowing about the temporary copy. Its evidence is **redacted**, like any artifact +on disk — the full evidence stayed on your terminal. And `saw` never deletes it; your operating +system clears its temporary directory on its own schedule, which may be at reboot or not at all. If +you want the report kept somewhere you chose, pass `-d DIR` and it goes there instead. + +`--json` turns the spill off: that payload already carries every finding in full, so there is +nothing to rescue from scrollback. A `-d DIR` you asked for is still written.