icsprio 1.0.0__tar.gz

icsprio-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+*.env
+data/raw/*
+!data/raw/.gitkeep
+!data/raw/PROVENANCE.txt
+.DS_Store
+*.log
+.coverage
+htmlcov/

icsprio-1.0.0/AUTHORS.json

@@ -0,0 +1,27 @@
+{
+  "_comment": "Author block for icsprio. Every document, citation file, Zenodo record, manuscript author list, and commit identity reads from here.",
+  "authors": [
+    {
+      "name": "Friday Ogochukwu Ikwuogu",
+      "family": "Ikwuogu",
+      "given": "Friday Ogochukwu",
+      "orcid": "0009-0009-2222-1318",
+      "email": "Friday.ikwuogu@gmail.com",
+      "affiliation": "Independent Researcher, Odessa, Texas, USA",
+      "roles": ["Conceptualization", "Methodology", "Software", "Data curation", "Validation", "Writing - original draft"],
+      "corresponding": true
+    }
+  ],
+  "collaborators": [
+    {
+      "name": "David Mike-Ewewie",
+      "family": "Mike-Ewewie",
+      "given": "David",
+      "orcid": "",
+      "email": "mike_d63291@utpb.edu",
+      "affiliation": "Computer Science Department, University of Texas Permian Basin, Odessa, Texas, USA",
+      "roles": ["Validation", "Writing - review and editing"],
+      "corresponding": false
+    }
+  ]
+}

icsprio-1.0.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Friday Ogochukwu Ikwuogu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This license covers the icsprio SOURCE CODE only. The joined/derived data
+files produced by running the pipeline (data/processed/*) are licensed
+separately under CC BY 4.0 — see LICENSE-DATA — because they are derived from
+third-party sources (CISA, FIRST.org, MITRE, the CVE Program) that require
+attribution. Those sources' own terms of use also continue to apply; see
+README.md § Sources.

icsprio-1.0.0/LICENSE-DATA

@@ -0,0 +1,20 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+The joined/derived data files produced by icsprio (everything under
+data/processed/, including icsprio_joined.csv and icsprio_joined.parquet)
+are licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/
+
+Attribution required when redistributing or building on these outputs:
+
+  Derived from icsprio (Ikwuogu & Mike-Ewewie), joining data from:
+    - CISA ICS Advisories (Cybersecurity and Infrastructure Security Agency,
+      U.S. Government work, public domain)
+    - CISA Known Exploited Vulnerabilities (KEV) Catalog (public domain)
+    - EPSS scores, FIRST.org, Inc. (see https://www.first.org/epss/ for terms)
+    - CISA Vulnrichment (https://github.com/cisagov/vulnrichment, CC0-1.0)
+    - MITRE ATT&CK for ICS (https://attack.mitre.org, subject to the ATT&CK
+      Terms of Use: https://attack.mitre.org/resources/terms-of-use/)
+
+Each underlying source's own license/terms continue to apply to that
+source's contribution to the joined output; CC BY 4.0 governs icsprio's own
+joining, scoring, and derived columns.

icsprio-1.0.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: icsprio
+Version: 1.0.0
+Summary: Fetch, join, and prioritize ICS vulnerability intelligence from CISA ICS Advisories, KEV, EPSS, Vulnrichment, and ATT&CK for ICS.
+Project-URL: Homepage, https://github.com/foikwuogu/icsprio
+Project-URL: Repository, https://github.com/foikwuogu/icsprio
+Project-URL: Issues, https://github.com/foikwuogu/icsprio/issues
+Project-URL: Documentation, https://github.com/foikwuogu/icsprio/tree/main/docs
+Author-email: Friday Ogochukwu Ikwuogu <Friday.ikwuogu@gmail.com>
+Maintainer-email: Friday Ogochukwu Ikwuogu <Friday.ikwuogu@gmail.com>
+License: MIT
+License-File: AUTHORS.json
+License-File: LICENSE
+License-File: LICENSE-DATA
+Keywords: attack,cisa,critical-infrastructure,cybersecurity,epss,ics,kev,ot,scada,vulnerability-management,vulnrichment
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.57; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: responses>=0.24; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14.0; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# icsprio
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22732040.svg)](https://doi.org/10.5281/zenodo.22732040)
+
+**Status:** v1.0.0 (verified — see [Verification](#verification)) | **Maintainer:** Friday Ogochukwu Ikwuogu, [ORCID 0009-0009-2222-1318](https://orcid.org/0009-0009-2222-1318) | **License:** code [MIT](LICENSE), joined data [CC BY 4.0](LICENSE-DATA)
+
+icsprio is an open Python package that fetches, joins, and prioritizes ICS
+(industrial control systems) vulnerability intelligence from five public
+sources — CISA ICS Advisories, the CISA Known Exploited Vulnerabilities
+(KEV) catalog, FIRST.org's EPSS, CISA's Vulnrichment SSVC/CVSS enrichment,
+and MITRE ATT&CK for ICS — into one deterministic, reproducible table with
+an OT-relevant priority score. It is built for operators, researchers, and
+auditors who need a defensible, explainable answer to "which of these ICS
+advisories should we act on first," instead of five browser tabs and a
+spreadsheet.
+
+Every number icsprio produces is reproducible: given the same fetched data
+and the same scoring weights, two runs never disagree, and every weight and
+mapping decision is documented and author-reviewed, not a black box.
+
+## What is here
+
+```
+icsprio/                    the installable package (fetchers, join, scoring, QA, CLI)
+icsprio/reference_data/     cwe_to_attack_ics.csv — the author-reviewed CWE->ATT&CK crosswalk
+code/                       numbered scripts in run order (thin wrappers over icsprio/)
+data/raw/                   inputs as fetched, with PROVENANCE.txt (created by `fetch`)
+data/processed/             joined table, qa_report.txt, stats.json (created by `build`)
+docs/                       CODEBOOK, SCORING, ATTACK_MAPPING, LIMITATIONS, VERIFY_CHECKLIST, NEXT_STEPS
+tests/                      offline pytest suite (fixtures only, no network calls)
+paper/                      JOSS-format paper draft (prepared, not yet submitted)
+```
+
+## Install
+
+```bash
+pip install icsprio            # once published to PyPI
+# or, from a clone:
+pip install -e ".[dev,parquet]"
+```
+
+Requires Python 3.9+. Runtime dependencies are deliberately minimal:
+`requests`, `pandas`, `click`, `PyYAML`.
+
+## Run it
+
+```bash
+icsprio run                 # fetch + join + score + QA in one call
+icsprio report               # print the QA report
+```
+
+or, to re-score already-fetched data (e.g. after editing `docs/SCORING.md`'s
+weights) without hitting the network again:
+
+```bash
+icsprio fetch --since-year 2023
+icsprio build --weights-file my_weights.yaml
+```
+
+or the numbered scripts, if you'd rather not install the CLI:
+
+```bash
+python code/01_fetch.py --since-year 2023
+python code/02_build.py
+python code/03_qa.py
+```
+
+A stranger should be able to run any of the above from this README alone
+and get `data/processed/icsprio_joined.csv` and `qa_report.txt`.
+
+### Default scope
+
+By default, `fetch` pulls ICS advisories from the last 3 years
+(`--since-year <current year - 3>`), not the full historical archive. This
+is a deliberate default, not a limitation of the data — see
+[docs/LIMITATIONS.md](docs/LIMITATIONS.md) for why, and pass
+`--since-year 2010` (or any earlier year) for a full historical pull. Set
+the `GITHUB_TOKEN` environment variable to raise GitHub's API rate limit
+for larger pulls.
+
+## Sources
+
+| Source | What it provides | Vintage | License / terms | Accessed |
+|---|---|---|---|---|
+| [CISA ICS Advisories (CSAF 2.0)](https://www.cisa.gov/news-events/ics-advisories), via [cisagov/CSAF](https://github.com/cisagov/CSAF) | Advisory metadata, vendor/product, CVEs | ongoing | U.S. Government work, public domain | 2026-09-13 |
+| [CISA KEV catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Confirmed real-world exploitation | updated continuously | U.S. Government work, public domain | 2026-09-13 |
+| [FIRST.org EPSS](https://www.first.org/epss/) | Exploitation-likelihood score | daily, back to 2021-04-14 | FIRST.org terms of use | 2026-09-13 |
+| [CISA Vulnrichment](https://github.com/cisagov/vulnrichment) | SSVC decision points, CVSS, CWE | ongoing (partial CVE coverage) | CC0-1.0 | 2026-09-13 |
+| [MITRE ATT&CK for ICS](https://github.com/mitre-attack/attack-stix-data) | Adversary technique catalog | versioned releases | ATT&CK Terms of Use | 2026-09-13 |
+
+## How prioritization works
+
+`priority_score` (0-100) is a deterministic weighted combination of KEV
+status, EPSS percentile, and Vulnrichment's SSVC decision points. The exact
+weights and the rationale for each are in [docs/SCORING.md](docs/SCORING.md)
+— **read that before trusting or citing a score**; it is icsprio's own
+analytic contribution, not a value CISA or FIRST publishes. `attack_technique_ids`
+comes from a documented, author-reviewed CWE-to-ATT&CK-for-ICS heuristic
+crosswalk (no authoritative CVE-to-technique mapping exists) — see
+[docs/ATTACK_MAPPING.md](docs/ATTACK_MAPPING.md).
+
+## Headline numbers
+
+From `data/processed/stats.json`, generated by a real `icsprio run` against
+live sources (2026-09-13, `--since-year 2023`):
+
+- 1,685 advisories fetched, 8,653 (advisory, CVE) rows, 7,107 unique CVEs
+- Join match rates: KEV 1.0%, EPSS 99.7%, Vulnrichment 78.9%, ATT&CK-for-ICS mapped 5.9%
+- Priority bands: Critical 83, High 37, Medium 1,978, Low 6,555
+- 0 sanity-check problems
+
+Re-run `icsprio run` yourself and these numbers regenerate from your own
+live fetch — never take them as static.
+
+## Verification
+
+This release has cleared the author verification gate
+([docs/VERIFY_CHECKLIST.md](docs/VERIFY_CHECKLIST.md)): a live `icsprio run`
+against real sources, the full `pytest` suite passing, and a hand review of
+`docs/SCORING.md`'s weights and `icsprio/reference_data/cwe_to_attack_ics.csv`'s
+crosswalk.
+
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for what remains provisional
+by design (e.g. the crosswalk is a documented heuristic, not a MITRE
+mapping) rather than unfinished.
+
+## Publishing
+
+Published on GitHub and archived on Zenodo
+([10.5281/zenodo.22732040](https://doi.org/10.5281/zenodo.22732040)); see
+[docs/PUBLISH_GUIDE.md](docs/PUBLISH_GUIDE.md) for PyPI steps.
+
+## Citation
+
+See [CITATION.cff](CITATION.cff). DOI:
+[10.5281/zenodo.22732040](https://doi.org/10.5281/zenodo.22732040).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Authors
+
+See [AUTHORS.json](AUTHORS.json) — the single source of truth for
+authorship across this README, CITATION.cff, the JOSS paper, and Zenodo
+metadata.

icsprio-1.0.0/README.md

@@ -0,0 +1,146 @@
+# icsprio
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22732040.svg)](https://doi.org/10.5281/zenodo.22732040)
+
+**Status:** v1.0.0 (verified — see [Verification](#verification)) | **Maintainer:** Friday Ogochukwu Ikwuogu, [ORCID 0009-0009-2222-1318](https://orcid.org/0009-0009-2222-1318) | **License:** code [MIT](LICENSE), joined data [CC BY 4.0](LICENSE-DATA)
+
+icsprio is an open Python package that fetches, joins, and prioritizes ICS
+(industrial control systems) vulnerability intelligence from five public
+sources — CISA ICS Advisories, the CISA Known Exploited Vulnerabilities
+(KEV) catalog, FIRST.org's EPSS, CISA's Vulnrichment SSVC/CVSS enrichment,
+and MITRE ATT&CK for ICS — into one deterministic, reproducible table with
+an OT-relevant priority score. It is built for operators, researchers, and
+auditors who need a defensible, explainable answer to "which of these ICS
+advisories should we act on first," instead of five browser tabs and a
+spreadsheet.
+
+Every number icsprio produces is reproducible: given the same fetched data
+and the same scoring weights, two runs never disagree, and every weight and
+mapping decision is documented and author-reviewed, not a black box.
+
+## What is here
+
+```
+icsprio/                    the installable package (fetchers, join, scoring, QA, CLI)
+icsprio/reference_data/     cwe_to_attack_ics.csv — the author-reviewed CWE->ATT&CK crosswalk
+code/                       numbered scripts in run order (thin wrappers over icsprio/)
+data/raw/                   inputs as fetched, with PROVENANCE.txt (created by `fetch`)
+data/processed/             joined table, qa_report.txt, stats.json (created by `build`)
+docs/                       CODEBOOK, SCORING, ATTACK_MAPPING, LIMITATIONS, VERIFY_CHECKLIST, NEXT_STEPS
+tests/                      offline pytest suite (fixtures only, no network calls)
+paper/                      JOSS-format paper draft (prepared, not yet submitted)
+```
+
+## Install
+
+```bash
+pip install icsprio            # once published to PyPI
+# or, from a clone:
+pip install -e ".[dev,parquet]"
+```
+
+Requires Python 3.9+. Runtime dependencies are deliberately minimal:
+`requests`, `pandas`, `click`, `PyYAML`.
+
+## Run it
+
+```bash
+icsprio run                 # fetch + join + score + QA in one call
+icsprio report               # print the QA report
+```
+
+or, to re-score already-fetched data (e.g. after editing `docs/SCORING.md`'s
+weights) without hitting the network again:
+
+```bash
+icsprio fetch --since-year 2023
+icsprio build --weights-file my_weights.yaml
+```
+
+or the numbered scripts, if you'd rather not install the CLI:
+
+```bash
+python code/01_fetch.py --since-year 2023
+python code/02_build.py
+python code/03_qa.py
+```
+
+A stranger should be able to run any of the above from this README alone
+and get `data/processed/icsprio_joined.csv` and `qa_report.txt`.
+
+### Default scope
+
+By default, `fetch` pulls ICS advisories from the last 3 years
+(`--since-year <current year - 3>`), not the full historical archive. This
+is a deliberate default, not a limitation of the data — see
+[docs/LIMITATIONS.md](docs/LIMITATIONS.md) for why, and pass
+`--since-year 2010` (or any earlier year) for a full historical pull. Set
+the `GITHUB_TOKEN` environment variable to raise GitHub's API rate limit
+for larger pulls.
+
+## Sources
+
+| Source | What it provides | Vintage | License / terms | Accessed |
+|---|---|---|---|---|
+| [CISA ICS Advisories (CSAF 2.0)](https://www.cisa.gov/news-events/ics-advisories), via [cisagov/CSAF](https://github.com/cisagov/CSAF) | Advisory metadata, vendor/product, CVEs | ongoing | U.S. Government work, public domain | 2026-09-13 |
+| [CISA KEV catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Confirmed real-world exploitation | updated continuously | U.S. Government work, public domain | 2026-09-13 |
+| [FIRST.org EPSS](https://www.first.org/epss/) | Exploitation-likelihood score | daily, back to 2021-04-14 | FIRST.org terms of use | 2026-09-13 |
+| [CISA Vulnrichment](https://github.com/cisagov/vulnrichment) | SSVC decision points, CVSS, CWE | ongoing (partial CVE coverage) | CC0-1.0 | 2026-09-13 |
+| [MITRE ATT&CK for ICS](https://github.com/mitre-attack/attack-stix-data) | Adversary technique catalog | versioned releases | ATT&CK Terms of Use | 2026-09-13 |
+
+## How prioritization works
+
+`priority_score` (0-100) is a deterministic weighted combination of KEV
+status, EPSS percentile, and Vulnrichment's SSVC decision points. The exact
+weights and the rationale for each are in [docs/SCORING.md](docs/SCORING.md)
+— **read that before trusting or citing a score**; it is icsprio's own
+analytic contribution, not a value CISA or FIRST publishes. `attack_technique_ids`
+comes from a documented, author-reviewed CWE-to-ATT&CK-for-ICS heuristic
+crosswalk (no authoritative CVE-to-technique mapping exists) — see
+[docs/ATTACK_MAPPING.md](docs/ATTACK_MAPPING.md).
+
+## Headline numbers
+
+From `data/processed/stats.json`, generated by a real `icsprio run` against
+live sources (2026-09-13, `--since-year 2023`):
+
+- 1,685 advisories fetched, 8,653 (advisory, CVE) rows, 7,107 unique CVEs
+- Join match rates: KEV 1.0%, EPSS 99.7%, Vulnrichment 78.9%, ATT&CK-for-ICS mapped 5.9%
+- Priority bands: Critical 83, High 37, Medium 1,978, Low 6,555
+- 0 sanity-check problems
+
+Re-run `icsprio run` yourself and these numbers regenerate from your own
+live fetch — never take them as static.
+
+## Verification
+
+This release has cleared the author verification gate
+([docs/VERIFY_CHECKLIST.md](docs/VERIFY_CHECKLIST.md)): a live `icsprio run`
+against real sources, the full `pytest` suite passing, and a hand review of
+`docs/SCORING.md`'s weights and `icsprio/reference_data/cwe_to_attack_ics.csv`'s
+crosswalk.
+
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for what remains provisional
+by design (e.g. the crosswalk is a documented heuristic, not a MITRE
+mapping) rather than unfinished.
+
+## Publishing
+
+Published on GitHub and archived on Zenodo
+([10.5281/zenodo.22732040](https://doi.org/10.5281/zenodo.22732040)); see
+[docs/PUBLISH_GUIDE.md](docs/PUBLISH_GUIDE.md) for PyPI steps.
+
+## Citation
+
+See [CITATION.cff](CITATION.cff). DOI:
+[10.5281/zenodo.22732040](https://doi.org/10.5281/zenodo.22732040).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Authors
+
+See [AUTHORS.json](AUTHORS.json) — the single source of truth for
+authorship across this README, CITATION.cff, the JOSS paper, and Zenodo
+metadata.

icsprio-1.0.0/code/01_fetch.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Fetch every source and write data/raw/_fetch_manifest.json.
+
+Equivalent to `icsprio fetch`; kept as a numbered script so the repository
+matches the project's standard run-in-order layout even for someone who
+hasn't installed the package as a CLI.
+
+Usage: python code/01_fetch.py [--since-year YYYY]
+"""
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from icsprio import pipeline  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--since-year", type=int, default=None)
+    args = ap.parse_args()
+    manifest = pipeline.run_fetch(since_year=args.since_year)
+    for stage, count in manifest["stage_counts"].items():
+        print(f"{stage}: {count}")
+
+
+if __name__ == "__main__":
+    main()

icsprio-1.0.0/code/02_build.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Join, score, and write data/processed/icsprio_joined.{csv,parquet}.
+
+Usage: python code/02_build.py [--weights-file weights.yaml]
+"""
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from icsprio import io_utils, pipeline  # noqa: E402
+from icsprio.cli import _load_weights  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--weights-file", default=None)
+    args = ap.parse_args()
+
+    manifest = pipeline.load_manifest()
+    weights = _load_weights(args.weights_file)
+    df = pipeline.run_build(manifest, weights=weights)
+
+    io_utils.export_csv(df, "data/processed/icsprio_joined.csv")
+    io_utils.export_parquet(df, "data/processed/icsprio_joined.parquet")
+    print(f"Wrote {len(df)} rows to data/processed/icsprio_joined.csv")
+
+
+if __name__ == "__main__":
+    main()

icsprio-1.0.0/code/03_qa.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Generate data/processed/qa_report.txt and stats.json from the built table.
+
+Usage: python code/03_qa.py [--final]
+"""
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import pandas as pd  # noqa: E402
+
+from icsprio import io_utils, pipeline  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--final", action="store_true")
+    args = ap.parse_args()
+
+    manifest = pipeline.load_manifest()
+    df = pd.read_csv("data/processed/icsprio_joined.csv")
+    # list-typed columns round-trip through CSV as "a; b" strings; restore lists
+    for col in ("vendors", "products", "cwes", "attack_technique_ids", "attack_technique_names"):
+        df[col] = df[col].fillna("").apply(lambda v: [s for s in str(v).split("; ") if s])
+
+    stats, report_text = pipeline.run_qa(df, manifest["stage_counts"], draft=not args.final)
+    io_utils.write_stats_json(stats, "data/processed/stats.json")
+    with open("data/processed/qa_report.txt", "w", encoding="utf-8") as f:
+        f.write(report_text)
+    print(report_text)
+
+
+if __name__ == "__main__":
+    main()

icsprio-1.0.0/docs/ATTACK_MAPPING.md

@@ -0,0 +1,60 @@
+# CWE -> ATT&CK-for-ICS crosswalk methodology
+
+**Author-reviewed heuristic:** This crosswalk is icsprio's own heuristic,
+authored for this project. It is not a MITRE, CISA, or CVE Program mapping;
+every row in `icsprio/reference_data/cwe_to_attack_ics.csv` has been reviewed
+by the author.
+
+## Why a crosswalk is needed at all
+
+No authoritative mapping from a CVE (or its CWE weakness class) to ATT&CK
+for ICS techniques exists. ATT&CK for ICS catalogs *adversary behavior after
+an initial foothold or during an intrusion* (e.g. "Modify Parameter," "Denial
+of Service"); CWE catalogs *root-cause weakness types* in software (e.g.
+"Out-of-bounds Write," "Missing Authentication"). They describe different
+things at different points in an intrusion, so there is no clean 1:1
+mapping — this crosswalk is a documented, reviewable judgment call about
+which techniques an adversary would plausibly use *given* a vulnerability of
+a certain weakness class, not a claim that exploiting CWE-X always produces
+technique T.
+
+## Method
+
+1. For each CWE commonly seen in ICS advisories, ask: if an adversary
+   exploited a vulnerability of this weakness class, what's the most direct
+   ATT&CK-for-ICS technique describing what they could then do?
+2. Assign one or more mapped techniques, each with:
+   - `confidence`: `high` (the technique's own ATT&CK description names
+     this weakness class or a direct synonym), `medium` (a common,
+     well-established path but not a definitional match), or `low` (plausible
+     but more context-dependent).
+   - `rationale`: one sentence, so a reader can judge the mapping rather
+     than trust it.
+3. `icsprio.join` keeps only the highest-confidence mapping per technique
+   when multiple CWEs on the same CVE point to the same technique, and
+   drops any mapped technique that isn't in the currently-fetched ATT&CK
+   catalog (so a stale crosswalk entry can never claim a retired ID).
+
+## Coverage
+
+The initial crosswalk (`icsprio/reference_data/cwe_to_attack_ics.csv`) covers
+roughly the two dozen CWEs most frequently assigned in CISA ICS advisories
+and Vulnrichment records (hard-coded/missing credentials, injection
+families, memory-safety bugs, denial-of-service-prone weaknesses,
+cryptographic/transport weaknesses, and access-control failures). A CWE not
+in the table simply contributes no mapped technique — this is silent by
+design (see NEXT_STEPS.md for surfacing "unmapped CWE" explicitly).
+
+## Extending it
+
+Add a row to `icsprio/reference_data/cwe_to_attack_ics.csv` with the same five
+columns (`cwe_id, cwe_name, attack_technique_id, attack_technique_name,
+confidence, rationale`) and re-run `icsprio build` — no code change needed.
+`tests/test_attack_mapping.py` confirms the loader and dedup logic handle
+new rows correctly.
+
+## Terms of use
+
+ATT&CK for ICS content (technique names, IDs, tactics) is used under the
+[ATT&CK Terms of Use](https://attack.mitre.org/resources/terms-of-use/),
+which permits use with attribution to MITRE ATT&CK.

icsprio-1.0.0/docs/CODEBOOK.md

@@ -0,0 +1,44 @@
+# Codebook — `data/processed/icsprio_joined.csv`
+
+One row per (advisory, CVE) pair. An advisory with no listed CVE keeps one
+row with `cve` empty.
+
+| Column | Type | Source | Definition |
+|---|---|---|---|
+| `advisory_id` | string | CISA CSAF | Advisory tracking ID, e.g. `ICSA-26-076-03`. |
+| `advisory_type` | string | derived | `ICSA` (general ICS/OT) or `ICSMA` (medical device), from the ID prefix. |
+| `title` | string | CISA CSAF | Advisory document title. |
+| `published` | date | CISA CSAF | `document.tracking.initial_release_date`. |
+| `updated` | date | CISA CSAF | `document.tracking.current_release_date`. |
+| `vendors` | list[string] | CISA CSAF | Vendor name(s) from the advisory's product tree. |
+| `products` | list[string] | CISA CSAF | Affected product name(s). |
+| `advisory_url` | string | derived | Human-readable advisory page. |
+| `cve` | string | CISA CSAF | The CVE ID this row is about. |
+| `in_kev` | bool | CISA KEV | Whether `cve` appears in the KEV catalog at fetch time. |
+| `kev_date_added` | date | CISA KEV | Date CISA added this CVE to KEV, if applicable. |
+| `kev_due_date` | date | CISA KEV | Federal remediation due date (Binding Operational Directive scope), if applicable. |
+| `kev_ransomware_use` | string | CISA KEV | `Known` or `Unknown` — known use in ransomware campaigns. |
+| `epss_score` | float [0,1] | FIRST EPSS | Estimated 30-day exploitation probability, at fetch time. |
+| `epss_percentile` | float [0,1] | FIRST EPSS | This CVE's percentile rank among all scored CVEs, at fetch time. |
+| `epss_date` | date | FIRST EPSS | The date EPSS scored this CVE (EPSS is point-in-time — see LIMITATIONS). |
+| `ssvc_exploitation` | categorical | Vulnrichment | CISA-ADP's SSVC Exploitation decision point: `none` / `poc` / `active`. |
+| `ssvc_automatable` | categorical | Vulnrichment | SSVC Automatable decision point: `no` / `yes`. |
+| `ssvc_technical_impact` | categorical | Vulnrichment | SSVC Technical Impact decision point: `partial` / `total`. |
+| `cvss_base_score` | float [0,10] | Vulnrichment | CVSS base score from the CISA-ADP container, when present. |
+| `cvss_vector` | string | Vulnrichment | CVSS vector string. |
+| `cwes` | list[string] | Vulnrichment | CWE weakness ID(s) CISA-ADP assigned to this CVE. |
+| `attack_technique_ids` | list[string] | derived | ATT&CK-for-ICS technique IDs mapped from `cwes` via the heuristic crosswalk — see ATTACK_MAPPING.md. **Not** a MITRE or CISA mapping. |
+| `attack_technique_names` | list[string] | derived | Names matching `attack_technique_ids`. |
+| `priority_score` | float [0,100] | derived | icsprio's own OT-relevant priority score — see SCORING.md. |
+| `priority_band` | categorical | derived | `Critical` / `High` / `Medium` / `Low`, from `priority_score` thresholds in SCORING.md. |
+
+## Missing values
+
+- `epss_score`/`epss_percentile`/`epss_date` are null when a CVE is too new
+  or otherwise unscored by EPSS at fetch time — not zero.
+- `ssvc_*`, `cvss_*`, and `cwes` are null/empty when Vulnrichment has not
+  yet enriched that CVE — CISA-ADP enriches a subset of CVEs, prioritizing
+  recent and higher-signal ones, not every CVE ever published.
+- `attack_technique_ids` is empty both when a CVE has no CWE assignment and
+  when its CWE(s) aren't yet in the crosswalk table — these two cases are
+  not currently distinguished in the output; see NEXT_STEPS.md.