Zero Breach — local, read-only scanner that checks a computer for indicators of the AdFection / Candiru ad-delivered spyware campaign. No network, no admin, no dependencies.
Prepare Zero Breach 0.1.3 release documentation and bundle
interplains6a57889df078
diff --git a/DETECTION-UPGRADE.md b/DETECTION-UPGRADE.mdindex 6dd2468..f44d395 100644--- a/DETECTION-UPGRADE.md+++ b/DETECTION-UPGRADE.md@@ -1,8 +1,8 @@-# Candiru pattern upgrade: unreleased research candidate+# Optional Candiru file patterns: validation and limits-This branch adds an optional check to Zero Breach itself. It is not a separate-product and has not replaced the signed v0.1.2 release or the website download.-The development version is 0.1.3.dev0. It is not approved for publication.+Zero Breach v0.1.3 adds an optional check to the existing scanner. The default+scan remains unchanged. This document records what the new mode checks, how it+was tested and where its results are limited.## Scope@@ -82,12 +82,14 @@ ran 267 tests with seven expected skips. The disposable Linux VM ran all 52pattern/integration tests without failures or skips. A small clean corpus of200 Debian files and 26 official Python Windows PE files produced no matches.-The revised development candidate is SHA-256-`2b30cc710a6f1fc326ef29d57e38e9f98279c428d8713d7aa85d0c905b54e549`.+The reviewed release build is SHA-256+`1a1eb0e76cd2791349be9861840a5756940c3a950a134b5436bc7f9d1b50e3b8`.After the prune correction and a Windows Python 3.12 file-metadata compatibilityfix, the Windows suite ran 269 tests with no failures and one permission skip;-without the optional engine it ran 269 tests with seven expected skips. These are development receipts;-version and packaging changes require a new final hash and checks.+without the optional engine it ran 269 tests with seven expected skips. The+release build changes the displayed version and help text, not the two rules+or file scanning logic. The signed final artifact and cross-platform CI must+still match this exact hash before publication.Two hash-verified MalwareBazaar downloads were scanned as static bytes insidethe disconnected VM, without execution:@@ -107,8 +109,9 @@ shared folders. It has been removed; only sanitized results were exported.These two positives and the small clean corpus demonstrate useful additionalcoverage, not a measured detection rate or proof of broad Candiru coverage.New native macOS execution, actual cloud placeholders and an adversarial-wall-clock engine-timeout case remain untested. The live v0.1.2 release remains-unchanged. Detailed local receipts are under `findings/vm-lab/`.+wall-clock engine-timeout case remain untested. At validation time the live+v0.1.2 release remained unchanged. Detailed local receipts are under+`findings/vm-lab/`.## MVT integration assessmentdiff --git a/README.md b/README.mdindex f215886..bcfac58 100644--- a/README.md+++ b/README.md@@ -1,9 +1,8 @@# Zero Breach-> Development branch: optional Candiru pattern scanning is under validation.-> It is not part of the signed v0.1.2 release. See-> [the upgrade scope and test gate](DETECTION-UPGRADE.md). The optional mode-> needs a pinned YARA-X dependency; default checks remain standard-library-only.+> Release v0.1.3 adds an optional Candiru file-pattern check. See+> [its scope and validation](DETECTION-UPGRADE.md). It needs a pinned YARA-X+> dependency; default checks remain standard-library-only.[](https://github.com/interplains/zero-breach/actions/workflows/tests.yml)@@ -79,7 +78,7 @@ browser before scanning so its databases are not locked.## Install and run-Requires Python 3.8 or newer. No administrator. No third-party packages.+Default checks require Python 3.8 or newer, no administrator and no added packages.**Single file (simplest):** [download zero-breach.py](https://github.com/interplains/zero-breach/releases/latest/download/zero-breach.py),verify it using the [release checksums](https://github.com/interplains/zero-breach/releases/latest),@@ -92,6 +91,28 @@ python -X utf8 zero-breach.py --quick # faster; skips file fingerprintingpython -X utf8 zero-breach.py --json report.json```+**Optional Candiru file patterns:** Download `requirements-patterns.txt` from+the same release as the scanner. This mode needs Python 3.9 or newer. From the+folder containing both downloads, make a separate Python environment and install+the hash-pinned YARA-X wheel:++```text+# Windows PowerShell+python -m venv .venv+.venv\Scripts\python.exe -m pip install -r requirements-patterns.txt+.venv\Scripts\python.exe -X utf8 zero-breach.py --patterns++# macOS / Linux+python3 -m venv .venv+.venv/bin/python -m pip install -r requirements-patterns.txt+.venv/bin/python -X utf8 zero-breach.py --patterns+```++`--pattern-path ABSOLUTE_PATH` limits this extra file check to a chosen local+file or folder; it can be repeated. The normal browser, hash and host checks keep+their usual scope. Pattern matches are leads for investigation, not proof of an+active infection. A no-match result cannot rule out Candiru or other spyware.+**From source:**```@@ -113,7 +134,7 @@ set up (e.g. a bad indicator file).Use the official repository above and check the downloaded file before running it.-**1. Verify the publisher's signature.** Release v0.1.2 includes detached GPG+**1. Verify the publisher's signature.** Release v0.1.3 includes detached GPGsignatures for the scanner and its checksum manifest, using ArchiveGenocide'sestablished release key. Follow [SIGNING.md](SIGNING.md), and compare the fullkey fingerprint with [ArchiveGenocide's verification page](https://archivegenocide.com/verify.html).@@ -137,11 +158,11 @@ you do not have to trust the download at all; you can reproduce it:```git clone https://github.com/interplains/zero-breach.gitcd zero-breach-git checkout v0.1.2+git checkout v0.1.3python build/build.py # writes dist/zero-breach.py and prints its SHA-256```-These commands reproduce v0.1.2; substitute the matching tag for another release.+These commands reproduce v0.1.3; substitute the matching tag for another release.On macOS or Linux use `python3` for the build command.Compare the hash with that release's published hash. The development branch maycontain later changes and is not expected to reproduce an earlier release.@@ -283,7 +304,7 @@ It downloads over HTTPS, checks the file against a published SHA-256, confirms iparses before replacing anything, and shows a diff first. The trust model and theupdater limitations are documented at the top of the script. It does not verifyGPG signatures automatically. The signed release manifest authenticates the IOC-file shipped with v0.1.2, not later development-branch updates; see [SIGNING.md](SIGNING.md).+file shipped with the signed release, not later development-branch updates; see [SIGNING.md](SIGNING.md).## Design principlesdiff --git a/SIGNING.md b/SIGNING.mdindex d481371..54af98d 100644--- a/SIGNING.md+++ b/SIGNING.md@@ -1,17 +1,17 @@# Verifying ArchiveGenocide release signatures-Zero Breach v0.1.2 supplies detached GPG signatures for the exact released+Zero Breach v0.1.3 supplies detached GPG signatures for the exact releasedscanner and its SHA256SUMS.txt manifest. They use ArchiveGenocide's existingEd25519 release-signing key, also published on the archive's verification page.Official repository: https://github.com/interplains/zero-breach-Official release: https://github.com/interplains/zero-breach/releases/tag/v0.1.2+Official release: https://github.com/interplains/zero-breach/releases/tag/v0.1.3Independent publisher page: https://archivegenocide.com/scan/#verify-downloadEstablished key identity: https://archivegenocide.com/verify.html## Check the publisher and file-Download these three files from the v0.1.2 release into one directory:+Download these three files from the v0.1.3 release into one directory:- zero-breach.py- zero-breach.py.asc@@ -36,9 +36,9 @@ Verification must succeed using the expected ArchiveGenocide key. A warningthat the key is not certified by your own web of trust is different from abad signature; do not ignore a fingerprint mismatch or failed verification.-The expected SHA-256 of zero-breach.py v0.1.2 is:+The expected SHA-256 of zero-breach.py v0.1.3 is:- f12f4a8dd15b00e6f2d7997f238780e43e7d82b689c6dfd5f4544b5d899c1a69+ 1a1eb0e76cd2791349be9861840a5756940c3a950a134b5436bc7f9d1b50e3b8A signature verifies which key signed these exact bytes. It does not establishthat the program has no bugs. A checksum alone is not publisher authentication.@@ -54,17 +54,18 @@ the manifest before using its checksums:Then compare the files with the signed manifest (for example,sha256sum -c SHA256SUMS.txt on Linux, orshasum -a 256 -c SHA256SUMS.txt on macOS).-The manifest lists the ten release-content files. The manifest itself and+The manifest lists the fifteen release-content files, including the optional+requirements file and Candiru rule attribution and licence records. The manifest itself andthe added public key/signatures are not self-listed.-Public verification artifacts are also retained in release-signatures/v0.1.2/.+Public verification artifacts are also retained in release-signatures/v0.1.3/.No private key is stored in this repository or in its project backups.## Indicator updates are a separate trust pathThe manually run scan/update-iocs.py still checks HTTPS, a published SHA-256,and indicator-file validity. It does not automatically verify GPG signatures.-The signed release manifest covers the indicator file shipped with v0.1.2;+The signed release manifest covers the indicator file shipped with v0.1.3;it does not authenticate later files fetched from the development branch.## Maintainer release procedurediff --git a/build/bundle.py b/build/bundle.pyindex 6092e2b..539dd52 100644--- a/build/bundle.py+++ b/build/bundle.py@@ -116,8 +116,9 @@ A('WHAT IT WILL NOT DO')A(' - It does not change source files, registry entries or system settings.')A(' It writes temporary database snapshots and embedded indicator data,')A(' removes those after use, and retains a report only when requested.')-A(' - It makes no intentional network requests or indicator lookups. Remote')-A(' and redirected paths are skipped; Authenticode checks are disabled.')+A(' - It makes no intentional network requests or indicator lookups. Redirected')+A(' paths and Windows remote drives are skipped; POSIX network mounts can')+A(' appear local and may be read. Authenticode checks are disabled.')A(' Python network calls are blocked during the scan. This guard is not an')A(' operating-system network sandbox.')A(' - It does not decrypt credentials. Cookie queries select metadata, not')@@ -146,11 +147,11 @@ A('')A('USAGE')A(' python -X utf8 zero-breach.py')A(' python -X utf8 zero-breach.py --json report.json')+A(' python -X utf8 zero-breach.py --patterns # optional YARA-X setup required')A('')A('Requires Python 3.8 or newer. Needs no administrator. All supported platforms')A('get browser and file checks; Windows also gets host checks.')A('Experimental --patterns also requires Python 3.9+ and yara-x==1.21.0.')-A('This development build is not an approved release.')A('"""')A('from __future__ import annotations')A('')@@ -159,7 +160,7 @@ A('import datetime')A('import sys')A('import time')A('')-A('__version__ = "0.1.3.dev0 (single-file build)"')+A('__version__ = "0.1.3 (single-file build)"')A('')A('# --- embedded indicator data ------------------------------------------------')A('# The real file is iocs/adfection_iocs.txt in the project. Its provenance')diff --git a/scan/README.md b/scan/README.mdindex 7e19761..22b56b4 100644--- a/scan/README.md+++ b/scan/README.md@@ -1,8 +1,8 @@# adint-scan-> This development branch includes experimental `--patterns` support. See+> Release v0.1.3 adds experimental, opt-in `--patterns` support. See> [DETECTION-UPGRADE.md](../DETECTION-UPGRADE.md) for dependencies, limits and-> validation requirements. It has not replaced the signed public release.+> validation evidence. Default checks need no added packages.A local, read-only check for the published AdFection / Candiru indicators,with explicit reporting of missing evidence and checks that could not run.@@ -39,7 +39,7 @@ python -X utf8 adint-scan.py``````-adint-scan [--deep] [--quick] [--json PATH] [--iocs PATH]+adint-scan [--deep] [--quick] [--json PATH] [--iocs PATH] [--patterns] [--pattern-path ABSOLUTE_PATH]```| flag | effect |@@ -49,6 +49,8 @@ adint-scan [--deep] [--quick] [--json PATH] [--iocs PATH]| `--json PATH` | also write the machine-readable report || `--iocs PATH` | use a different indicator file (default `../iocs/adfection_iocs.txt`) || `--deep` | tier 2: full persistence sweep. Not implemented — the flag reports an honest `UNKNOWN` gap rather than faking a sweep |+| `--patterns` | opt-in, bounded check against two published Candiru file rules; requires Python 3.9+ and the pinned optional YARA-X wheel |+| `--pattern-path ABSOLUTE_PATH` | file or folder for the optional pattern check; repeatable and requires `--patterns` |Exit codes: `0` nothing found, `2` an indicator matched, `1` the scan could notbe set up. This release changes no system settings and needs no administrator.@@ -62,6 +64,7 @@ after use. `--json PATH` writes the report you request.| `browser` | history, cookies, favicons, HTTP cache, LevelDB and Service Worker caches across Chrome / Edge / Brave / Vivaldi / Chromium (every profile) and Firefox. Locked databases are copied before being opened. || `hash` | SHA-256 of candidate files under AppData, ProgramData, both Temps, Downloads, Desktop, Documents and Public, against the sample hashes in the IOC set. || `host` | per-user COM registrations (this chain's documented persistence), the DNS resolver cache, whether DNS history exists at all, and the hosts file. |+| `patterns` (optional) | file bytes checked against two published Candiru research rules; a match needs investigation and cannot confirm infection |Why the browser module looks at the cache and not just history: history recordsonly top-level navigations, and an ad is a subresource inside an iframe. A realdiff --git a/scan/adint_scan/__init__.py b/scan/adint_scan/__init__.pyindex c74e99f..8d4fc42 100644--- a/scan/adint_scan/__init__.py+++ b/scan/adint_scan/__init__.py@@ -4,4 +4,4 @@ A clean result from this tool means "no known indicators were found in the placethat can be checked." It does NOT mean the device is clean. See SPEC-scanner.md."""-__version__ = "0.1.3.dev0"+__version__ = "0.1.3"