Skip to content

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.md
index 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 52
pattern/integration tests without failures or skips. A small clean corpus of
200 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 compatibility
fix, 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 inside
the 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 additional
coverage, 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 assessment
diff --git a/README.md b/README.md
index 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.
[![tests](https://github.com/interplains/zero-breach/actions/workflows/tests.yml/badge.svg)](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 fingerprinting
python -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 GPG
signatures for the scanner and its checksum manifest, using ArchiveGenocide's
established release key. Follow [SIGNING.md](SIGNING.md), and compare the full
key 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.git
cd zero-breach
-git checkout v0.1.2
+git checkout v0.1.3
python 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 may
contain 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 i
parses before replacing anything, and shows a diff first. The trust model and the
updater limitations are documented at the top of the script. It does not verify
GPG 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 principles
diff --git a/SIGNING.md b/SIGNING.md
index 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 released
scanner and its SHA256SUMS.txt manifest. They use ArchiveGenocide's existing
Ed25519 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.3
Independent publisher page: https://archivegenocide.com/scan/#verify-download
Established 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 warning
that the key is not certified by your own web of trust is different from a
bad 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
+ 1a1eb0e76cd2791349be9861840a5756940c3a950a134b5436bc7f9d1b50e3b8
A signature verifies which key signed these exact bytes. It does not establish
that 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, or
shasum -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 and
the 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 path
The 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 procedure
diff --git a/build/bundle.py b/build/bundle.py
index 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.md
index 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 not
be 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 records
only top-level navigations, and an ad is a subresource inside an iframe. A real
diff --git a/scan/adint_scan/__init__.py b/scan/adint_scan/__init__.py
index 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 place
that can be checked." It does NOT mean the device is clean. See SPEC-scanner.md.
"""
-__version__ = "0.1.3.dev0"
+__version__ = "0.1.3"