IF Commons GitHub

Scanners: running a scanner

0004Active

0004-scanners-run · owner if · domain commons

Requirements

FR-001checkpassing

A run MUST be refused, with the reason and a record and before anything else is done, where the scanner is unknown, the target is of the wrong kind or unfit (0002-scanners-catalog FR-002), or a path does not exist.

Enforced (check): .github: cd commons/scanners && bun run verify — suite/run.test.ts

Proved by: scanners/suite/run.test.ts

Written in: scanners/src/physical/run.ts

Tests: passed: suite/run.test.ts a run is refused with the reason and a record, before anything else, for an unknown scanne

FR-002checkpassing

A run MUST ask the engagement whether the scanner's technique is allowed on the asset before any tool is looked for, any file is read or anything is sent to a target, and MUST do nothing more where the answer is no; the asset asked about is the estate's asset, never a name the target or the output gives.

Enforced (check): .github: cd commons/scanners && bun run verify — suite/run.test.ts

Proved by: scanners/suite/run.test.ts

Written in: scanners/src/physical/run.ts

Tests: passed: suite/run.test.ts the engagement is asked first for the scanner's technique on the estate's asset, and a no

FR-003checkpassing

A tool MUST be run only when it has a pin and the file at the pin's path exists and has the pinned SHA-256; a tool with no pin, a missing file or a file with another digest MUST be refused and MUST NOT be run, and the refusal MUST say which and give the digest it found.

Enforced (check): .github: cd commons/scanners && bun run verify — suite/run.test.ts

Proved by: scanners/suite/run.test.ts

Written in: scanners/src/physical/run.ts

Tests: passed: suite/run.test.ts a tool runs only when it has a pin and the file has the pinned digest: a missing pin, a mi

FR-004checkpassing

A tool MUST be run with an argument vector (never a shell), in an empty working folder that is removed afterwards, with only a bare PATH, a HOME in that folder and the language and colour settings, and MUST be stopped when its time limit passes.

Enforced (check): .github: cd commons/scanners && bun run verify — suite/run.test.ts

Proved by: scanners/suite/run.test.ts

Written in: scanners/src/physical/run.ts

Tests: passed: suite/run.test.ts a tool is started with a list of arguments, in an empty folder that is removed afterwards,

FR-005checkpassing

What a tool prints (or the file it writes) MUST be read by the findings importers, every finding MUST be about the estate's asset the run was for, and an output that is empty or that no importer reads MUST be a refusal that says so; every run, refused or made, MUST give a record of the scanner, the asset, the target, the technique, the time, the tool's name, version and digest, the exit code and the number of findings.

Enforced (check): .github: cd commons/scanners && bun run verify — suite/run.test.ts

Proved by: scanners/suite/run.test.ts

Written in: scanners/src/physical/run.ts

Tests: passed: suite/run.test.ts the built-in check needs no pin, is asked as a probe, and gives findings about the asset f; passed: suite/run.test.ts what a tool prints is read into findings about the estate's asset, an empty or unreadable

Acceptance scenarios

  1. Given an engagement that does not allow scan on the asset, When nuclei is run, Then no tool is started, per FR-002.
  2. Given a pinned tool that was changed after it was pinned, When it is run, Then it is refused with both digests, per FR-003.
  3. Given a pinned tool that prints a report, When it is run, Then its findings are about the asset, per FR-005.

Out of scope

  • Installing or fetching a tool, and pinning it: the owner does, with opsfolio scan pin.

Edge cases

  • A target, a tool or an answer that is not as required is refused, never run or kept, per the requirements above (FR-001).

Assumptions

  • None.

Open questions

  • None.

Key entities

  • Scanner, Pin, Run record.

Success criteria

SC-001success criterion

The tests of the library pass.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Scanners: the catalog

Titles, headings, exports, tables, columns and requirements. Esc closes.