scanfuse 0.2.0__tar.gz

scanfuse-0.2.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

scanfuse-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv*/
+.runtime/
+.pytest*/
+.mypy_cache/
+.ruff_cache/
+node_modules/
+build/
+dist/
+*.egg-info/
+.env
+.env.*
+!.env.example
+.hypothesis/

scanfuse-0.2.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## 0.2.0 (2026-11-07)
+
+The project is renamed from `repx` to `scanfuse` (the name `repx` is taken on PyPI). The command, the Python package, the configuration file (`.repx.yaml` is now `.scanfuse.yaml`) and the environment variable for the packaged-program tests (`REPX_EXE` is now `SCANFUSE_EXE`) changed. repx 0.1 was never published.
+
+This version changes the JSON format and the merge rules. Read "Changed" before you update scripts.
+
+### Changed
+
+* **`report.json` is now an object**, not a list: `{"schema_version": 2, "complete": true, "errors": [], "findings": [...]}`. Scripts that read the list must read `["findings"]` instead.
+* **Merging is stricter.** Findings are merged only when the titles are equal (ignoring case and surrounding spaces), they have the same CVE or GHSA ids and the same port, and the same tool does not give them different tool ids. Similar titles are no longer merged. A merged finding keeps every host and every piece of evidence, and the description, remediation, severity, CVSS score and vector of each tool are listed in `sources`.
+* CSV: `Hosts` shows `ip (host name)` when a host name is known. Six columns were added after the original eight: `CVSS Vector`, `Port`, `Identifiers`, `References`, `Other Reports`, `Import Status`.
+* `--host` matches the IP or host name exactly (ignoring case). Before, it matched any part of the text, so `10.0.0.1` also matched `10.0.0.10`. `*` and `?` are wildcards.
+* `--min-severity`, `--format`, `--format-out` accept only their documented values. `--template-dir` must exist. A wrong value now stops with exit code 2.
+* An invalid `.scanfuse.yaml` (wrong types, not a mapping, YAML syntax error) is an error: exit code 1 and an incomplete report.
+* The Markdown index lists findings by severity (before: alphabetically by severity name).
+* Titles, host names, ids and tool names are escaped in the Markdown, so scanner text cannot add links or headings there. Descriptions keep their formatting but cannot create headings.
+* Version 0.2.0. The version is defined only in `scanfuse/__init__.py`.
+
+### Added
+
+* **References and CWE ids.** Links that the scanner gives for a finding (ZAP `reference`, Burp `references`, Nessus `see_also`, Trivy `References` and `PrimaryURL`, Nuclei `info.reference`) are kept in the new field `references`. They appear under "References" in the Markdown and HTML report, in the JSON, and in the new CSV column `References`. CWE ids (ZAP `cweid`, Burp classifications, Trivy `CweIDs`) are identifiers. WASC ids from ZAP too.
+* Nessus: the synopsis is put in front of the description, CVSS v3 is used if there is no v2 score, and the placeholder solution "n/a" is no longer shown as a remediation. Burp: confidence and location are kept in an evidence entry.
+* `tools/check_public_samples.py` downloads the twelve public files, compares the number of findings with an independent count, merges, exports in all formats and prints the time. All twelve pass; the largest (2,587 ZAP alerts, 1,427 Trivy findings) take 1.4 s.
+* Existing reports are protected. scanfuse stops with exit code 2 if files would be overwritten. With `--replace`, it builds the new report in a temporary folder and attempts to restore the old report if publication fails. A failed recovery retains backups; a process or system crash can leave a mixed report.
+* A Nuclei JSONL file with malformed lines retains valid findings and marks the report incomplete.
+* Reports from partly failed runs are marked: `complete: false` and `errors` in the JSON, an INCOMPLETE notice in `index.md` and `report.html`, and an `Import Status` column in the CSV.
+* Ids and ports are kept: CVE, GHSA and CWE ids, and tool ids such as `nessus-plugin:12345`, as `identifiers`, and the port as `port`.
+* Evidence records which tool reported it when findings are merged.
+* `--csv-excel` (byte order mark, `;` separator), `--replace`, `--version`.
+* MIT `LICENSE`, package metadata, a source package without internal files.
+* `tools/large_check.py` for large inputs. CI builds and tests standalone programs on Linux, Windows and macOS, runs the tests on Python 3.12 and 3.13, checks the dependencies with pip-audit and installs the wheel in a clean environment.
+
+### Fixed
+
+Found by running scanfuse on twelve real scanner files from the public [DefectDojo sample-scan-files](https://github.com/DefectDojo/sample-scan-files) repository (MIT license): Nmap 6.40 and 7.12, ZAP 1.4, Trivy (three schemas), Nessus, Burp.
+
+* **Burp files were not detected.** The format check read 1,024 characters, but Burp writes a long DTD in front of the first tag (`<issues>` starts at about byte 3,400). The file was then read as nmap and failed. scanfuse now reads 64 KB.
+* **Older Trivy files were not read.** They are a plain JSON list of results without `SchemaVersion`. They were taken for Nuclei and failed. Both Trivy schemas are supported now.
+* **ZAP 1.x reports gave one finding titled "Unknown Vulnerability".** Old ZAP files have `<alert>` instead of `<name>` and keep the URL, parameter and attack in the alert itself instead of in `<instances>`. In the sample, all 67 alerts had the same title, were merged into one, and lost their URLs. Now the title, the affected URL, the parameter, the attack and the other info are read. Newer ZAP files also keep `param`, `attack` and `otherinfo` of every instance now.
+* Burp, ZAP and Nessus text fields contain HTML (`<p>`, `<br>`, `<li>`, `&quot;`). The report showed the markup as text. It is converted to plain text now, with line breaks and list items kept.
+* nmap: the operating system guess was dropped. The guess with the highest accuracy is kept now, for example `Linux 5.0 - 5.7 (97%)`. The CPE names that version detection reports (`cpe:/a:...`) were dropped too and are kept as identifiers. Found by running nmap 7.94 against the local machine and comparing its XML with scanfuse's output.
+* A scan without any open port (host down, all ports closed, list scan) ended without a word. scanfuse now says that the input contains no findings and that nothing was exported.
+* Merging lost data: description, remediation, CVSS score and vector of the other tools, findings with the same title but different CVEs, packages or ports, and the second operating system of a host.
+* A finding titled "Index" or "Report", or named like a Windows device (`CON`, `NUL`, `COM1`), overwrote or collided with other files.
+* Evidence was escaped twice and changed (`<` became `&lt;`, three backticks became `'''`). It is now written unchanged inside a code fence that is longer than any backtick run in the data.
+* Formula protection in CSV missed look-alike characters such as a full-width `＝` and a leading no-break space.
+* `-f nuclei` on a file of another format produced a bogus finding. It is now an error.
+* A missing file was reported as "could not auto-detect format". A directory or an output path that is a file caused a traceback. XML with entities gave a raw exception name. Messages for standard input showed the name of a temporary file. Square brackets in a file name could break the output.
+* The wheel and the source package had no license, and the source package contained local planning files with user paths.
+
+### Measured
+
+Not a reference system: one Linux machine in the cloud (Ubuntu glibc 2.39, 4 CPUs, 16 GB). 100,000 results, 50,000 distinct titles, each repeated on another host with other evidence. All hosts, all evidence entries and the number of findings were checked after each run.
+
+| Output | Time | Peak memory |
+|---|---|---|
+| JSON | 13.9 s | 909 MB |
+| CSV | 10.4 s | 687 MB |
+| Markdown with index and HTML | 123.9 s | 1040 MB |
+
+### Checked with real scanner output
+
+* Nmap 7.94 was run against 127.0.0.1: service and version scan with scripts, OS detection, a scan with only closed ports, a host discovery scan and a list scan. Two of those files are in `tests/fixtures/` (`real_nmap_*`).
+* Twelve public files from the DefectDojo sample repository (see above). Eight of them are in `tests/fixtures/public/` with their license; the rest are downloaded by `tools/check_public_samples.py`.
+* Nuclei has no public sample file in that repository. The Nuclei parser is still tested only with hand-made files. A real Nuclei export would help.
+* The sample files are old (2013 to 2024). Current versions of ZAP, Burp, Nessus and Trivy may have fields that these files do not show.
+
+### Not checked
+
+* The HTML report in a browser by hand (search, severity filter, keyboard, narrow window).
+* The CSV in Excel and LibreOffice. Only the file content was checked.
+* Standalone programs on other Linux distributions (Debian, Kali, Fedora, Arch, Alpine), Linux on ARM and macOS on Intel.
+* Whether the Windows program starts on a clean Windows 11 machine without developer tools. CI builds and tests it on a Windows runner.
+
+## 0.1.0 (named repx)
+
+First version. Not published.

scanfuse-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Issues and pull requests are welcome. For a larger change, open an issue first.
+
+## Set up and test
+
+```bash
+uv sync --locked --extra dev
+uv run ruff check .
+uv run mypy scanfuse
+uv run pytest tests/
+```
+
+## Rules
+
+* Keep a change small and add a test that fails without it.
+* Scanner files are untrusted input. A parser must not execute, fetch or trust anything in them.
+* A new fixture must come from a public source with a license that allows redistribution, or be made by you. Remove hostnames, IP addresses and credentials first. Never add files from a real client engagement.
+* Security problems: see [SECURITY.md](SECURITY.md), do not open a public issue.

scanfuse-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gencay
+
+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.

scanfuse-0.2.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: scanfuse
+Version: 0.2.0
+Summary: Fast, local-first pentest finding extractor & markdown report engine.
+Project-URL: Repository, https://github.com/gencay-e/scanfuse
+Project-URL: Changelog, https://github.com/gencay-e/scanfuse/blob/main/CHANGELOG.md
+Author: Gencay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: burp,nessus,nmap,nuclei,pentest,report,security,trivy,zap
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: defusedxml<1,>=0.7.1
+Requires-Dist: jinja2<4,>=3.1.3
+Requires-Dist: markdown<4,>=3.11
+Requires-Dist: nh3<1,>=0.3.7
+Requires-Dist: pydantic<3,>=2.7.0
+Requires-Dist: pyyaml<7,>=6.0.1
+Requires-Dist: rich<16,>=13.7.0
+Requires-Dist: typer<1,>=0.12.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pyinstaller>=6.5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scanfuse
+
+A local command-line tool that reads pentest scanner reports and writes one report from them.
+
+<img alt="Scan files from Nmap, Nuclei, ZAP, Burp, Nessus and Trivy go into scanfuse, which writes index.md, report.html, report.json and report.csv" src="docs/images/scanfuse-flow.svg" width="900">
+
+It imports Nmap, Nuclei, ZAP, Burp, Nessus and Trivy files and writes Markdown (with an index and a standalone HTML page), JSON or CSV. It runs offline and sends nothing anywhere.
+
+Version 0.2.0, a pre-release. See [CHANGELOG.md](CHANGELOG.md).
+
+## Example
+
+<img alt="The summary of a report" src="docs/images/report-summary.png" width="900">
+
+<img alt="A finding in the report" src="docs/images/report-finding.png" width="900">
+
+`report.html` follows the light or dark setting of your system; the screenshots show the dark one.
+
+The report above was made from six real scan files (Nmap, ZAP, Trivy, Burp, Nessus). The input files, the
+command and the full report are in [examples/](examples/).
+
+## Install
+
+You need Python 3.12 or newer.
+
+```bash
+pipx install scanfuse                                   # from PyPI
+pipx install git+https://github.com/gencay-e/scanfuse   # latest state from GitHub
+```
+
+`pip install scanfuse` works as well. From a checkout of this repository: `pipx install .`
+
+Ready-made programs for Linux, Windows and macOS (no Python needed) are on the [Releases page](https://github.com/gencay-e/scanfuse/releases), with a `SHA256SUMS` file. To build one yourself, see [Build a standalone program](#build-a-standalone-program).
+
+## Use
+
+```bash
+scanfuse scan.xml -o report
+scanfuse nmap.xml nuclei.json zap.xml -o report
+scanfuse scan.json -f trivy --format-out json -o report
+scanfuse scan.xml --min-severity High --host 192.0.2.1 -o report
+cat scan.json | scanfuse -o report
+```
+
+`scanfuse` takes one or more files, or `-` for standard input. It finds the format by itself. Use `-f` to choose one: `nmap`, `nuclei`, `zap`, `burp`, `nessus`, `trivy`.
+
+| Option | Meaning |
+|---|---|
+| `-o`, `--output` | Output directory. Default `report`. |
+| `--format-out` | `markdown` (default), `json` or `csv`. `markdown` writes one file per finding, `index.md` and `report.html`. |
+| `-s`, `--min-severity` | `Critical`, `High`, `Medium`, `Low` or `Info`. Case does not matter. |
+| `--host` | Only findings on this host. Must match the IP or host name exactly, ignoring case. `*` and `?` are wildcards, for example `10.0.0.*`. |
+| `-t`, `--template-dir` | Folder with your own `finding.md.j2` and `index.md.j2`. The folder must exist. Missing files fall back to the built-in templates. |
+| `--replace` | Overwrite an existing report. See below. |
+| `--csv-excel` | CSV with a byte order mark and `;` as separator, which German-language Excel expects. |
+| `--version` | Print the version. |
+
+### Existing reports
+
+`scanfuse` never overwrites files by accident. If the output directory already contains a file that the new report would write, it stops with exit code 2 and changes nothing. Add `--replace` to overwrite the report. With `--replace`, files of the earlier report that are no longer part of it are removed. Files that scanfuse did not write are left alone.
+
+The report is built in a temporary folder first. If moving the files fails, scanfuse tries to restore the old report. If restoration also fails, the error gives the location of the retained backup. A process or system crash during replacement can still leave a mixed report.
+
+### Incomplete runs
+
+If one input file cannot be read, scanfuse still writes the findings from the other files and exits with code 1. The report says so:
+
+* `report.json`: `"complete": false` and the list of `errors`.
+* `index.md` and `report.html`: an **INCOMPLETE** notice with the errors.
+* `report.csv`: the column `Import Status` says `incomplete (...)` in every row.
+
+An invalid `.scanfuse.yaml` counts as an error too. The report is then incomplete, because ignore rules were not applied.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Complete. |
+| 1 | Incomplete or failed: an input could not be read, `.scanfuse.yaml` is invalid, nothing could be written, or no input was given. |
+| 2 | Invalid option, or the output files already exist (use `--replace`). |
+
+## Merging duplicates
+
+Findings from several files are merged when they are the same finding:
+
+* the titles are equal, ignoring case and surrounding spaces,
+* they carry the same CVE or GHSA ids,
+* they have the same port, and
+* the same tool does not give them different tool ids (for example two Nessus plugin ids).
+
+Titles that are only similar are not merged. A merged finding keeps all hosts and all evidence. Evidence shows which tool reported it. What each tool wrote (description, remediation, severity, CVSS score and vector, ids) is listed under **Reported by** in the Markdown and in `sources` in the JSON. The summary severity is the highest of all reports. The summary CVSS score is the highest score, together with its own vector.
+
+## Output
+
+### JSON
+
+`report.json` is an object:
+
+```json
+{
+  "schema_version": 2,
+  "complete": true,
+  "errors": [],
+  "findings": [ { "title": "...", "severity": "High", "identifiers": ["CVE-2024-0001"], "port": "443/tcp", "sources": [] } ]
+}
+```
+
+### CSV
+
+Columns: `Title`, `Severity`, `CVSS`, `Hosts`, `Source Tool`, `Description`, `Remediation`, `Evidence`, `CVSS Vector`, `Port`, `Identifiers`, `References`, `Other Reports`, `Import Status`. `Hosts` shows `ip (host name)` when a host name is known.
+
+Cells that start with `=`, `+`, `-` or `@` get a leading `'` to reduce the risk of spreadsheet formulas. This also covers look-alike characters such as a full-width `＝` and a leading no-break space. These cases were tested by reading the files back.
+
+In Excel, import `--csv-excel` output with **Data > From Text/CSV** and use the semicolon delimiter. In a Windows Excel test, this preserved a multiline evidence field; the older Text Import Wizard split it across rows. Formula handling and LibreOffice remain unverified in those applications.
+
+### Scanner text in the report
+
+Scanner output is untrusted. scanfuse treats it like this:
+
+* Titles, host names, ids and tool names are shown as plain text. They cannot add links, headings or HTML.
+* Descriptions and remediation text keep Markdown formatting, including links. Raw HTML is escaped, and the text cannot create a heading. A link in a scanner description is shown as the scanner wrote it, so check it before you click.
+* Evidence is shown unchanged in a code block.
+* The HTML page removes scripts, images, frames and `javascript:` links.
+* XML with entity declarations is rejected.
+
+## Configuration: `.scanfuse.yaml`
+
+`scanfuse` reads `.scanfuse.yaml` from the current directory.
+
+```yaml
+ignore_titles:
+  - "Wappalyzer"
+  - "Header Missing"
+```
+
+Findings whose title contains one of these texts (ignoring case) are left out. `ignore_titles` must be a list of strings. A single string is read as a list with one entry. Anything else, a file that is not a mapping, or a YAML syntax error is reported as an error and the rules are not applied.
+
+## Build a standalone program
+
+```bash
+uv sync --extra dev
+uv run python build.py
+```
+
+The program is written to `dist/`. To check it against the test suite:
+
+```bash
+SCANFUSE_EXE=dist/scanfuse uv run pytest tests/test_packaged_cli.py     # Linux, macOS
+$env:SCANFUSE_EXE = (Resolve-Path .\dist\scanfuse.exe).Path             # Windows PowerShell
+```
+
+A program built on Linux depends on the C library of the system it was built on. Build on the oldest system you want to support.
+
+## Development
+
+```bash
+uv sync --locked --extra dev
+uv run ruff check .
+uv run mypy scanfuse
+uv run pytest tests/
+```
+
+## Limits
+
+* scanfuse was tested with real output from nmap (7.94, 7.12, 6.40), ZAP 1.4, Burp, Nessus and Trivy (three file layouts), taken from the public [DefectDojo sample-scan-files](https://github.com/DefectDojo/sample-scan-files). Those files are old. Newer versions of the tools may add fields that scanfuse does not read yet. Nuclei has no real sample file in the tests. Open an issue with a cleaned sample if a file fails.
+* Format detection looks at the start of the file. Use `-f` if it guesses wrong.
+* The HTML page and the CSV file were checked by reading the files. They were not opened by hand in a browser, Excel or LibreOffice.
+* 100,000 results were processed completely in all three output formats on one Linux machine (4 CPUs, 16 GB). JSON took 14 seconds, CSV 10 seconds, Markdown with HTML 124 seconds, and the peak memory was between 0.7 and 1.0 GB. The HTML page for that many findings is large. You can repeat the check with `python tools/large_check.py 100000`.
+* Standalone programs are built and tested in CI on Ubuntu 22.04 (x86_64), Windows (x86_64) and macOS (arm64). Other Linux distributions, Linux on ARM and macOS on Intel were not tested.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

scanfuse-0.2.0/README.md

@@ -0,0 +1,173 @@
+# scanfuse
+
+A local command-line tool that reads pentest scanner reports and writes one report from them.
+
+<img alt="Scan files from Nmap, Nuclei, ZAP, Burp, Nessus and Trivy go into scanfuse, which writes index.md, report.html, report.json and report.csv" src="docs/images/scanfuse-flow.svg" width="900">
+
+It imports Nmap, Nuclei, ZAP, Burp, Nessus and Trivy files and writes Markdown (with an index and a standalone HTML page), JSON or CSV. It runs offline and sends nothing anywhere.
+
+Version 0.2.0, a pre-release. See [CHANGELOG.md](CHANGELOG.md).
+
+## Example
+
+<img alt="The summary of a report" src="docs/images/report-summary.png" width="900">
+
+<img alt="A finding in the report" src="docs/images/report-finding.png" width="900">
+
+`report.html` follows the light or dark setting of your system; the screenshots show the dark one.
+
+The report above was made from six real scan files (Nmap, ZAP, Trivy, Burp, Nessus). The input files, the
+command and the full report are in [examples/](examples/).
+
+## Install
+
+You need Python 3.12 or newer.
+
+```bash
+pipx install scanfuse                                   # from PyPI
+pipx install git+https://github.com/gencay-e/scanfuse   # latest state from GitHub
+```
+
+`pip install scanfuse` works as well. From a checkout of this repository: `pipx install .`
+
+Ready-made programs for Linux, Windows and macOS (no Python needed) are on the [Releases page](https://github.com/gencay-e/scanfuse/releases), with a `SHA256SUMS` file. To build one yourself, see [Build a standalone program](#build-a-standalone-program).
+
+## Use
+
+```bash
+scanfuse scan.xml -o report
+scanfuse nmap.xml nuclei.json zap.xml -o report
+scanfuse scan.json -f trivy --format-out json -o report
+scanfuse scan.xml --min-severity High --host 192.0.2.1 -o report
+cat scan.json | scanfuse -o report
+```
+
+`scanfuse` takes one or more files, or `-` for standard input. It finds the format by itself. Use `-f` to choose one: `nmap`, `nuclei`, `zap`, `burp`, `nessus`, `trivy`.
+
+| Option | Meaning |
+|---|---|
+| `-o`, `--output` | Output directory. Default `report`. |
+| `--format-out` | `markdown` (default), `json` or `csv`. `markdown` writes one file per finding, `index.md` and `report.html`. |
+| `-s`, `--min-severity` | `Critical`, `High`, `Medium`, `Low` or `Info`. Case does not matter. |
+| `--host` | Only findings on this host. Must match the IP or host name exactly, ignoring case. `*` and `?` are wildcards, for example `10.0.0.*`. |
+| `-t`, `--template-dir` | Folder with your own `finding.md.j2` and `index.md.j2`. The folder must exist. Missing files fall back to the built-in templates. |
+| `--replace` | Overwrite an existing report. See below. |
+| `--csv-excel` | CSV with a byte order mark and `;` as separator, which German-language Excel expects. |
+| `--version` | Print the version. |
+
+### Existing reports
+
+`scanfuse` never overwrites files by accident. If the output directory already contains a file that the new report would write, it stops with exit code 2 and changes nothing. Add `--replace` to overwrite the report. With `--replace`, files of the earlier report that are no longer part of it are removed. Files that scanfuse did not write are left alone.
+
+The report is built in a temporary folder first. If moving the files fails, scanfuse tries to restore the old report. If restoration also fails, the error gives the location of the retained backup. A process or system crash during replacement can still leave a mixed report.
+
+### Incomplete runs
+
+If one input file cannot be read, scanfuse still writes the findings from the other files and exits with code 1. The report says so:
+
+* `report.json`: `"complete": false` and the list of `errors`.
+* `index.md` and `report.html`: an **INCOMPLETE** notice with the errors.
+* `report.csv`: the column `Import Status` says `incomplete (...)` in every row.
+
+An invalid `.scanfuse.yaml` counts as an error too. The report is then incomplete, because ignore rules were not applied.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Complete. |
+| 1 | Incomplete or failed: an input could not be read, `.scanfuse.yaml` is invalid, nothing could be written, or no input was given. |
+| 2 | Invalid option, or the output files already exist (use `--replace`). |
+
+## Merging duplicates
+
+Findings from several files are merged when they are the same finding:
+
+* the titles are equal, ignoring case and surrounding spaces,
+* they carry the same CVE or GHSA ids,
+* they have the same port, and
+* the same tool does not give them different tool ids (for example two Nessus plugin ids).
+
+Titles that are only similar are not merged. A merged finding keeps all hosts and all evidence. Evidence shows which tool reported it. What each tool wrote (description, remediation, severity, CVSS score and vector, ids) is listed under **Reported by** in the Markdown and in `sources` in the JSON. The summary severity is the highest of all reports. The summary CVSS score is the highest score, together with its own vector.
+
+## Output
+
+### JSON
+
+`report.json` is an object:
+
+```json
+{
+  "schema_version": 2,
+  "complete": true,
+  "errors": [],
+  "findings": [ { "title": "...", "severity": "High", "identifiers": ["CVE-2024-0001"], "port": "443/tcp", "sources": [] } ]
+}
+```
+
+### CSV
+
+Columns: `Title`, `Severity`, `CVSS`, `Hosts`, `Source Tool`, `Description`, `Remediation`, `Evidence`, `CVSS Vector`, `Port`, `Identifiers`, `References`, `Other Reports`, `Import Status`. `Hosts` shows `ip (host name)` when a host name is known.
+
+Cells that start with `=`, `+`, `-` or `@` get a leading `'` to reduce the risk of spreadsheet formulas. This also covers look-alike characters such as a full-width `＝` and a leading no-break space. These cases were tested by reading the files back.
+
+In Excel, import `--csv-excel` output with **Data > From Text/CSV** and use the semicolon delimiter. In a Windows Excel test, this preserved a multiline evidence field; the older Text Import Wizard split it across rows. Formula handling and LibreOffice remain unverified in those applications.
+
+### Scanner text in the report
+
+Scanner output is untrusted. scanfuse treats it like this:
+
+* Titles, host names, ids and tool names are shown as plain text. They cannot add links, headings or HTML.
+* Descriptions and remediation text keep Markdown formatting, including links. Raw HTML is escaped, and the text cannot create a heading. A link in a scanner description is shown as the scanner wrote it, so check it before you click.
+* Evidence is shown unchanged in a code block.
+* The HTML page removes scripts, images, frames and `javascript:` links.
+* XML with entity declarations is rejected.
+
+## Configuration: `.scanfuse.yaml`
+
+`scanfuse` reads `.scanfuse.yaml` from the current directory.
+
+```yaml
+ignore_titles:
+  - "Wappalyzer"
+  - "Header Missing"
+```
+
+Findings whose title contains one of these texts (ignoring case) are left out. `ignore_titles` must be a list of strings. A single string is read as a list with one entry. Anything else, a file that is not a mapping, or a YAML syntax error is reported as an error and the rules are not applied.
+
+## Build a standalone program
+
+```bash
+uv sync --extra dev
+uv run python build.py
+```
+
+The program is written to `dist/`. To check it against the test suite:
+
+```bash
+SCANFUSE_EXE=dist/scanfuse uv run pytest tests/test_packaged_cli.py     # Linux, macOS
+$env:SCANFUSE_EXE = (Resolve-Path .\dist\scanfuse.exe).Path             # Windows PowerShell
+```
+
+A program built on Linux depends on the C library of the system it was built on. Build on the oldest system you want to support.
+
+## Development
+
+```bash
+uv sync --locked --extra dev
+uv run ruff check .
+uv run mypy scanfuse
+uv run pytest tests/
+```
+
+## Limits
+
+* scanfuse was tested with real output from nmap (7.94, 7.12, 6.40), ZAP 1.4, Burp, Nessus and Trivy (three file layouts), taken from the public [DefectDojo sample-scan-files](https://github.com/DefectDojo/sample-scan-files). Those files are old. Newer versions of the tools may add fields that scanfuse does not read yet. Nuclei has no real sample file in the tests. Open an issue with a cleaned sample if a file fails.
+* Format detection looks at the start of the file. Use `-f` if it guesses wrong.
+* The HTML page and the CSV file were checked by reading the files. They were not opened by hand in a browser, Excel or LibreOffice.
+* 100,000 results were processed completely in all three output formats on one Linux machine (4 CPUs, 16 GB). JSON took 14 seconds, CSV 10 seconds, Markdown with HTML 124 seconds, and the peak memory was between 0.7 and 1.0 GB. The HTML page for that many findings is large. You can repeat the check with `python tools/large_check.py 100000`.
+* Standalone programs are built and tested in CI on Ubuntu 22.04 (x86_64), Windows (x86_64) and macOS (arm64). Other Linux distributions, Linux on ARM and macOS on Intel were not tested.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

scanfuse-0.2.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report vulnerabilities privately and do not open a public issue. Use GitHub's private vulnerability reporting for this repository (Security tab, "Report a vulnerability").
+
+Supported: the latest release.
+
+## What scanfuse handles
+
+scanfuse reads scanner files that may come from untrusted targets (titles, banners and evidence are attacker-controlled text) and writes Markdown, HTML, JSON and CSV.
+
+* XML with entity declarations is rejected.
+* Titles, host names and ids are escaped in Markdown and HTML. The HTML page removes scripts, images, frames and `javascript:` links.
+* CSV cells that start with `=`, `+`, `-`, `@` or look-alike characters are prefixed with `'`.
+* Nothing is sent over the network.
+
+## Known limits
+
+* Descriptions and remediation text keep Markdown, including links. Links are shown as the scanner wrote them.
+* The HTML page and CSV output were checked by reading the files, not by opening them in a browser, Excel or LibreOffice.
+* Format detection looks at the start of the file.
+* Release programs are not signed. Releases come with a `SHA256SUMS` file.

scanfuse-0.2.0/SECURITY_MODEL.md

@@ -0,0 +1,57 @@
+# Security Model
+
+`scanfuse` is an offline command-line utility that imports pentest scanner outputs (Nmap, Nuclei, OWASP ZAP, Burp Suite, Nessus, and Trivy), deduplicates findings, and exports unified reports as Markdown, standalone HTML, JSON, or CSV.
+
+## Deployment Context
+
+* Runs as a local single-user CLI process (`scanfuse/cli.py`).
+* Performs local file I/O only. It opens no network sockets and makes no outbound HTTP or DNS requests.
+* Processes scanner output files that frequently contain attacker-controlled strings captured from scanned targets (HTTP banners, headers, responses, TLS subject names, and reflected payloads).
+
+## Trust Boundaries and Inputs
+
+### Untrusted Inputs
+
+* **Scanner input files** (`file_path` arguments and `stdin` in `scanfuse/cli.py`, parsed by `scanfuse/parsers/*.py`):
+  * XML inputs (`nmap.py`, `zap.py`, `burp.py`, `nessus.py`) and JSON/JSONL inputs (`nuclei.py`, `trivy.py`) are untrusted. Both the file structure and all embedded text fields (`title`, `description`, `remediation`, `host`, `evidence`, `references`, `identifiers`) may be attacker-controlled.
+
+### Trusted Operator Inputs
+
+* **Command-line arguments** (`--output`, `--format`, `--format-out`, `--min-severity`, `--host`, `--template-dir`, `--replace`, `--csv-excel`).
+* **Local configuration file** (`.scanfuse.yaml` in the current working directory, loaded via `yaml.safe_load` in `scanfuse/cli.py`).
+* **Custom Jinja2 templates** (`--template-dir`, loaded by `ScanfuseEngine._template_env` in `scanfuse/engine.py`).
+
+## Security Invariants
+
+1. **No XML External Entities (XXE) or DTD Expansion:**
+   All XML parsing in `scanfuse/parsers/nmap.py`, `zap.py`, `burp.py`, and `nessus.py` must use `defusedxml.ElementTree.iterparse` and reject entity or DTD declarations (`DefusedXmlException` caught in `ScanfuseEngine.process_file`).
+2. **HTML Sanitization in Standalone Reports:**
+   All Markdown fragments rendered into `report.html` must pass through `nh3.clean` in `scanfuse/html_report.py` (`render_report_fragment`), restricting elements to `REPORT_TAGS` (`a`, `b`, `blockquote`, `br`, `code`, `del`, `div`, `em`, `h1`–`h6`, `hr`, `i`, `li`, `ol`, `p`, `pre`, `s`, `strong`, `table`, `tbody`, `td`, `th`, `thead`, `tr`, `ul`) and URL schemes on `a[href]` to `http`, `https`, and `mailto`.
+3. **Markdown Escaping and Fence Isolation:**
+   * Scalar fields (`title`, `ip`, `hostname`, `os`, `source_tool`, `port`, `identifiers`) use the `md` filter (`md_escape` in `scanfuse/engine.py`) so they cannot inject HTML tags, Markdown links, or headings.
+   * Free-text fields (`description`, `remediation`) use the `mdtext` filter (`md_text` in `scanfuse/engine.py`), which HTML-escapes raw `<`/`>`/`&` and escapes leading `#`/`=`/`-` heading markers.
+   * Raw evidence blocks use the `fence` filter (`code_fence` in `scanfuse/engine.py`), which computes a backtick fence strictly longer than any backtick run inside the evidence payload.
+4. **Spreadsheet Formula Neutralization (CSV Injection):**
+   Every cell written by `ScanfuseEngine.export_csv` in `scanfuse/engine.py` must pass through `csv_safe`, which normalizes text with `NFKC` and prepends a single quote (`'`) whenever the normalized cell starts with `=`, `+`, `-`, or `@`, or the raw cell starts with whitespace (`\t`, `\r`, `\n`, space).
+5. **Safe Output File Names and Staged Publishing:**
+   * Per-finding Markdown file names are generated by `unique_slug` (`scanfuse/utils.py`), which restricts characters to `[a-z0-9-]`, caps length at 100 characters, and blocks `RESERVED_SLUGS` (`index`, `report`, Windows device names `con`, `prn`, `aux`, `nul`, `com1`–`com9`, `lpt1`–`lpt9`).
+   * `ScanfuseEngine._publish` writes into a temporary staging directory first, refuses to overwrite existing files without `--replace`, and ignores dot-files or path segments when cleaning up stale files from `.scanfuse-manifest-<kind>.json`.
+
+## In-Scope Vulnerability Classes
+
+* **XXE or XML entity expansion** bypassing `defusedxml` in `scanfuse/parsers/*.py`.
+* **Cross-Site Scripting (XSS)** in generated `report.html` via crafted scanner fields bypassing `md_escape`, `md_text`, `code_fence`, or `nh3.clean` (`scanfuse/engine.py`, `scanfuse/html_report.py`).
+* **Path traversal or arbitrary file overwrite** outside `--output` triggered by crafted finding titles, slugs, or manifest entries (`scanfuse/utils.py`, `scanfuse/engine.py`).
+* **CSV formula injection** bypassing `csv_safe` (`scanfuse/engine.py`).
+* **Unsafe deserialization** in configuration or parser loading (e.g., replacing `yaml.safe_load` in `scanfuse/cli.py`).
+
+## Out of Scope / Non-Issues
+
+* **Jinja2 `autoescape=False` in `ScanfuseEngine._template_env` (`scanfuse/engine.py`):**
+  Jinja2 renders Markdown templates (`finding.md.j2`, `index.md.j2`), not HTML directly. Escaping is enforced explicitly via the `| md`, `| mdtext`, and `| fence` template filters, and the resulting HTML is sanitized by `nh3.clean` in `scanfuse/html_report.py`.
+* **Malicious custom templates passed via `--template-dir` or local `.scanfuse.yaml`:**
+  The CLI user running `scanfuse` and choosing `--template-dir` or `.scanfuse.yaml` already executes with their own local user privileges.
+* **Scanner URLs in `references` or `description` pointing to external phishing/malicious sites:**
+  Preserving `http://` and `https://` links reported by scanners is intended behavior (documented in `SECURITY.md`); only non-web schemes such as `javascript:` or `data:` are in scope.
+* **Memory exhaustion on multi-gigabyte single-line inputs:**
+  Local resource consumption from oversized local files passed by the operator is a known operational limit, not a privilege boundary violation.

scanfuse-0.2.0/build.py

@@ -0,0 +1,23 @@
+import argparse
+from pathlib import Path
+
+import PyInstaller.__main__
+
+
+def build(output_dir: str = "dist", work_dir: str = "build"):
+    project_dir = Path(__file__).parent.resolve()
+    PyInstaller.__main__.run([
+        str(project_dir / "scanfuse.spec"),
+        '--clean',
+        '--noconfirm',
+        f'--distpath={project_dir / output_dir}',
+        f'--workpath={project_dir / work_dir}',
+        '--log-level=WARN',
+    ])
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Build the standalone scanfuse executable.")
+    parser.add_argument("--output-dir", default="dist")
+    parser.add_argument("--work-dir", default="build")
+    args = parser.parse_args()
+    build(args.output_dir, args.work_dir)