Skip to content
Skills Library
Security · Review & audit

finding-normalizer

/finding-normalizer

Turns mixed raw evidence from docs, tests, runtime checks and advisory feeds into stable finding entries with ids, severity, effort and status, deduplicating records of the same risk. Use when raw security or audit evidence must become report-ready findings JSON, or when findings or retest statuses need normalizing, validating or stable ids.

Repository
paqad-ai ↗
Licence
MIT
Last repository change
12.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/validate-findings.sh

What it does and when to use it

Turns mixed raw evidence from docs, tests, runtime checks and advisory feeds into stable finding entries with ids, severity, effort and status, deduplicating records of the same risk. Use when raw security or audit evidence must become report-ready findings JSON, or when findings or retest statuses need normalizing, validating or stable ids.

Original author description

Turns mixed raw evidence from docs, tests, runtime checks and advisory feeds into stable finding entries with ids, severity, effort and status, deduplicating records of the same risk. Use when raw security or audit evidence must become report-ready findings JSON, or when findings or retest statuses need normalizing, validating or stable ids.

How it works

  1. What It Does
  2. Use This When
  3. Inputs
  4. Procedure
  5. Output Contract
  6. Escalate / Stop Conditions
  7. Resources
Original SKILL.md headings · 50 lines, 356 words
SKILL.md preview
---
name: finding-normalizer
description: Turns mixed raw evidence from docs, tests, runtime checks and advisory feeds into stable finding entries with ids, severity, effort and status, deduplicating records of the same risk. Use when raw security or audit evidence must become report-ready findings JSON, or when findings or retest statuses need normalizing, validating or stable ids.
metadata:
  model_tier: medium
  cacheable: 'false'
  output_format: json
  paqad-meta: skill.meta.yaml
---

## What It Does

Normalizes evidence from docs, tests, runtime checks, and advisory feeds into stable finding entries with consistent ids, severity, effort, and reproduction data.

Finding-id prefixes recognised by the normalizer are listed under `# code-prefix` in `assets/vocabulary.txt`:

- `PEN-*`: pentest findings (security workflow).
- `DT-*`: design-test findings (design-system audit workflow). Categories: `token | component | state | a11y | responsive | motion | copy | performance | documentation-drift`. `token` findings default to **high** severity to surface hard-coded design values (hex literals, raw px/rem, ad-hoc font stacks where a token exists).
- `SM-*`: site-map findings (site-map / site-map-retest workflow; `docs/site-map/<ts>.json`). The id is a content-addressed `SM-<hash8>`; the `SM-ADD | SM-REMOVE | SM-EDGE-STALE | SM-GUARD-DRIFT | SM-JOURNEY-BROKEN | …` names are `category` values, listed under `# site-map category` in `assets/vocabulary.txt`.
- `MD-*`: prospective module decisions. Stored under `.paqad/decisions/module-decisions/<id>.yml`; the consumer is the Attribution Gate, not the pentest workflow. Treat severity/effort/status as advisory only for `MD-*`, the binding state machine lives in `src/module-decisions/schema.ts`.

## Use This When

After raw security evidence has been collected and needs to be turned into report-ready findings or retest statuses.

## Inputs

- Read the structured evidence payload first.
- Read `references/finding-fields.md` before setting severity or effort.
- Read retest state when the workflow is `pentest-retest`.

## Procedure

1. Deduplicate findings that describe the same risk surface.
2. Pick severity, effort, and status from the closed sets in `assets/vocabulary.txt`.
3. Preserve ids and prior statuses when normalizing retest output.
4. Format the JSON exactly per `assets/output.template.json`.
5. Validate with `scripts/validate-findings.sh`: checks required fields, vocabulary, and id uniqueness.

## Output Contract

- Match `assets/output.template.json`: a JSON array of findings with `id, title, severity, effort, impact_area, evidence, reproduction, status` (plus optional `wstg_id` / `owasp_2025`).
- `severity`, `effort`, `status` must come from `assets/vocabulary.txt`.
- Output must pass `scripts/validate-findings.sh` (exit 0).

## Escalate / Stop Conditions

- Ask when two evidence records appear to describe overlapping but not identical risks.
- Warn when the available evidence is too thin to support the proposed severity.
- Do not inflate severity to compensate for missing detail.

## Resources

- `references/finding-fields.md`
- `scripts/validate-findings.sh`
- `assets/output.template.json`
- `assets/vocabulary.txt`
- `agents/openai.yaml`
Files in this package (7)
  • SKILL.md 3 KB
  • skill.meta.yaml 1 KB
  • agents/openai.yaml 1 KB
  • assets/output.template.json 1 KB
  • assets/vocabulary.txt 2 KB
  • references/finding-fields.md 1 KB
  • scripts/validate-findings.sh 2 KB

Versions

The database has no other skills named finding-normalizer.

Database snapshot: 13.11.2026 · package version 595c2563ef11 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90ot-evidence-normalizer
    Convert offline JSON forensic reports from Modbus, BACnet, S7comm, IEC-104, and structured OT observations into validated event and process-observation schemas for incident reconstruction. Use when combining industrial forensic evidence across analysis tools.
  • 100finding-triage
    Triage a single security finding — from a scanner, audit, advisory, report, or a findings.json record — to a defensible disposition with calibrated severity, a mitigation plan, false-positive justification, or accepted-risk writeup. Use when the user mentions 'triage this…
  • 90board-report
    Turn raw security data (metrics, incident notes, project status, audit findings, spreadsheets) into a concise board, audit-committee or executive security report written in business language. Use when the user asks for a board report, CISO update, quarterly security report, exec…
  • 100vuln-report
    Turn one confirmed security finding into a disclosure-ready GitHub advisory with root cause, proof of concept, impact, and source evidence. Use for reporting an established vulnerability, not discovering or validating one.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.