raftward 0.1.1__tar.gz

raftward-0.1.1/LICENSE

@@ -0,0 +1,158 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal Entity
+authorized to submit on behalf of the copyright owner. For the purposes of this
+definition, "submitted" means any form of electronic, verbal, or written
+communication sent to the Licensor or its representatives, including but not
+limited to communication on electronic mailing lists, source code control
+systems, and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but excluding
+communication that is conspicuously marked or otherwise designated in writing by
+the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable patent license to make, have made, use,
+offer to sell, sell, import, and otherwise transfer the Work, where such license
+applies only to those patent claims licensable by such Contributor that are
+necessarily infringed by their Contribution(s) alone or by combination of their
+Contribution(s) with the Work to which such Contribution(s) was submitted. If
+You institute patent litigation against any entity (including a cross-claim or
+counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated
+within the Work constitutes direct or contributory patent infringement, then any
+patent licenses granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

raftward-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md REVIEW.md
+recursive-include examples *.toml
+recursive-include tests *.py

raftward-0.1.1/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: raftward
+Version: 0.1.1
+Summary: Offline, guarded integrity checks for closed SQLite databases and backups
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Dragon-Lady/raftward
+Project-URL: Issues, https://github.com/Dragon-Lady/raftward/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Dynamic: license-file
+
+# Raft Ward
+
+Raft Ward checks the integrity of closed SQLite databases, frozen exports, and
+backup folders. It detects missing files, corruption, suspicious shrinkage,
+permission changes, and patterns consistent with bulk encryption or renaming.
+It does not repair, restore, quarantine, or modify the files it watches.
+
+Version 0.1.1 is free software under Apache-2.0, for Linux with Python 3.10
+or newer. Its only runtime dependency is
+`tomli` on Python 3.10.
+
+## Posture
+
+- Local, read-only target access; no telemetry. No network or child processes by
+  default. Configured alert delivery is the only network feature.
+- Every watched target has configured owning applications. A running app or
+  background worker skips its own target, with its name and reason in the report.
+  Other targets continue. No metadata, hashing, or integrity work starts for a
+  target whose owner is already observed running.
+- Unknown process visibility or any configured nonlocal machine also defers the
+  entire run. A stale local status file never counts as remote closure.
+- Owner matching is generic and case insensitive across Linux `/proc` process
+  names, executable paths, and command lines. Cursor and Codex are defaults, not
+  special cases. There is no owning-process allowlist.
+- Targets are opened only with read-only descriptors, no locks. SQLite is never
+  connected to an original. Source symlinks, unsupported files, foreign-owned
+  paths, a visible same-UID foreign target/sidecar descriptor, transfer locks, and running
+  configured transfer programs defer the run.
+- Writes are restricted to private application state, an explicit new report
+  file, and disposable private SQLite copies under `$XDG_RUNTIME_DIR/raftward`.
+  Report/state/runtime locations cannot overlap configured target trees.
+- Persistent state contains local paths, keyed identifiers, file metadata,
+  SHA-256 file digests, entropy measurements, findings, and timestamps. It contains
+  no database rows, message text, file excerpts, full process arguments, or
+  conversation data. SQLite copies contain source bytes briefly and are deleted
+  in cleanup on success, deferral, interruption, or exception. On the next run,
+  stale private copies are removed from the runtime directory.
+
+Keep all involved applications and workers closed for the full run. A polling
+guard cannot establish an atomic interlock with an unrelated application. Raft
+Ward reaches one checkpoint after each 64 KiB source chunk, throughout
+directory walks, and every 100 SQLite virtual-machine instructions. Repeated
+process enumeration is throttled to a 100 ms interval measured from the end of
+the previous enumeration at these checkpoints.
+Mandatory checks bypass that interval before target metadata/open, initial source
+copying, private-copy creation, SQLite connection/integrity work, and completion.
+A slow process enumeration, bounded retry, or blocked filesystem call can extend
+the wall-clock delay; this is not a real-time deadline. Once a running owner is
+observed, that target's result is discarded while other targets continue; cleanup
+closes descriptors and removes its private copy. An app can start between a check
+and a syscall or entirely between
+checks. No zero-race protection is claimed.
+
+## Install and configure
+
+From a reviewed checkout:
+
+```sh
+python3 -m pip install .
+raftward --help
+```
+
+Copy and edit `examples/config.toml` into
+`$XDG_CONFIG_HOME/raftward/config.toml` (default
+`~/.config/raftward/config.toml`). Create that configuration with mode **0600**.
+There are no automatically scanned targets. Every target has a unique simple
+name, `path`, `class`, and nonempty `owners` list. If `owners` is omitted it
+defaults to all configured owners. The default owners are `cursor` and `codex`.
+
+```toml
+machines = ["local"]
+alert_channels = ["stdout"]
+
+[owners]
+notes = ["notes-app", "notes-worker"]
+
+[[targets]]
+name = "notes-export"
+path = "~/backups/notes.sqlite"
+class = "frozen"
+sqlite = true
+owners = ["notes"]
+```
+
+`live` tolerates ordinary hash and mtime changes. `frozen` flags changes in hash,
+size, or mtime. `folder` recursively checks mixed files and evaluates bulk changes
+since the last completed run. `sqlite = true` identifies an expected database
+even if its header is already damaged; it defaults true for `live`. Recognizable
+SQLite files found in any class also get integrity checks. Prefer explicit
+`sqlite = true` for frozen database exports.
+
+File and directory globs support `*`, `?`, and bracket patterns. Recursive `**`
+globs defer; use a `folder` target for recursive scanning. Symlinks are never
+followed. Defaults are 10,000 files and a 20-file mass-change threshold. A folder
+containing other users' files defers rather than silently skipping them. Broad
+owner substrings may yield conservative false positives.
+
+**Multi-machine operation:** list every involved machine in `machines`, including
+`local`. v0.1 cannot prove current remote app state and therefore always defers if
+this list includes another machine. There is no SSH, remote helper, status-file
+override, or network probe. Do not omit an involved machine to get around this
+gate. Coordinated cross-machine inspection remains a review/release gap.
+
+## Commands
+
+```sh
+raftward guard
+raftward baseline
+raftward check --quick --max-gb 2
+raftward check --target notes-export --format html --output /tmp/raft-report.html
+raftward accept notes-export --reason "verified closed export"
+raftward baseline export --format json
+raftward status
+raftward report --since 7d
+raftward report --since 24h --send
+raftward targets list
+raftward targets add packets ~/backups/packets --class folder --owner notes
+raftward targets remove packets
+raftward print-timer --interval 30m
+```
+
+All commands accept `--format text|json|md|html` and `--output NEW_FILE`.
+Global `--config FILE` and `--state DIR` options precede the command. Report
+destinations must already have a parent directory; existing files are never
+overwritten. Text output is a readable metadata record; JSON is structured data.
+Markdown and HTML escape all interpolated values and load no external assets.
+
+`guard` inspects process state and configured transfer-lock metadata only; it does
+not stat or open watched targets. `status`, `report`, `targets list`, and `baseline
+export` read stored application metadata only and do not scan sources. A guard
+result is valid at that checkpoint, not a promise about a later check.
+
+`baseline` captures all targets or `--target NAME`; replacing an existing baseline
+requires `--force`. `accept TARGET` re-baselines one reviewed change. Neither will
+bless missing targets, a lost expected SQLite header, failed integrity, or future
+mtime. An accept records time, target, and an HMAC fingerprint of the optional
+reason; it intentionally does **not** retain free text, which might contain
+credentials or personal conversation. `targets add/remove` writes a private
+complete target list in state that takes precedence over the TOML target list;
+owner definitions still come from TOML.
+
+Checks use `nice(10)` when allowed. `--max-gb` limits source bytes for the entire
+run; exceeding it defers rather than recording a partial success. The runtime
+directory must be available in `XDG_RUNTIME_DIR`. `--quick` requests
+`PRAGMA quick_check`; full `integrity_check` is the default.
+
+Exit codes: **0** no findings/success, **1** findings or rejected unsafe baseline,
+**2** usage/runtime/alert-delivery error, **3** deferred or partial check/guard/status. A report
+returns 1 when the requested history contains findings. Timer unit text is printed
+as report data only. Review the `ExecStart` executable path before installing
+units yourself; Raft Ward never installs, enables, or starts timers.
+
+## SQLite and transfer boundaries
+
+For a closed source without sidecars, Raft Ward copies bytes through bounded
+read-only reads into a unique 0700 directory. The copy is created 0600 before any
+bytes are written. Source device/inode, size, mtime, ctime, and mode are checked
+again. The copy is opened with `mode=ro&immutable=1`, `query_only=ON`,
+`trusted_schema=OFF`, and `temp_store=MEMORY`. Only `ok`/`not ok` and page count
+are retained from SQLite; diagnostic strings may reveal content and are discarded.
+
+**Any `-wal`, `-shm`, or `-journal` beside a SQLite target defers the entire run.**
+Raft Ward never assumes immutable mode validates uncheckpointed WAL contents. It
+does not checkpoint or remove sidecars. A closed WAL-mode main database without
+sidecars can be checked as a main-file snapshot. WAL reconstruction and live WAL
+integrity validation are explicitly unsupported.
+
+Configured `transfer_commands` default to `rclone` and `rsync`. Any matching
+process stops the entire run even when its arguments do not identify a target.
+This includes permanent `rclone mount` processes and rsync daemons: they can defer
+every run indefinitely. The 24-hour deferral notice names this conservative
+transfer policy. Subcommand/target attribution has not been proven safe and no
+mount or daemon exemption is applied. `transfer_dirs` stops work if a process
+command references a configured directory; `transfer_locks` and singular
+`transfer_lock` are supported. No process is stopped or signaled.
+
+Raft Ward requires a full host `/proc` view. A restricted `hidepid` mount defers;
+a PID namespace containing only a subset of the host is not proof that other
+owners are closed. Owner/worker and transfer matching uses `comm` plus `cmdline`
+for every visible process, with `exe` as supplementary identity when readable.
+Only Raft Ward's own PID is excluded; its parent, sibling processes, and workers
+are still checked. Same-UID identity/descriptor permission failures get three
+50 ms rereads. A persistently unavailable `exe` may be omitted when identity
+remains readable. A same-UID process whose `/proc/PID/fd` is kernel-owned, such
+as a non-dumpable user service, participates in name matching while its open-file
+check is reported as `unverifiable`. The same applies when fd entries remain
+listable but their readlinks return EACCES/EPERM after retries and the process's
+CapPrm or CapEff contains capabilities absent from our own. Readable fd links
+still participate in target-handle checks. Other unreadable same-UID identity
+or descriptors still defer.
+`process-descriptor-state-unknown` distinguishes descriptor visibility failure.
+
+Other-UID `exe` and descriptor access is normally restricted by Linux. Raft Ward
+matches those processes using readable `comm`/`cmdline`; at least one identity
+field must be readable. It does not inspect other-UID descriptors and cannot prove
+that another user (including root) has no target file open. This is an explicit
+visibility gap, not a closed-state claim. Transient ENOENT/ESRCH means a vanished
+process/descriptor; readable owner names are retained when only `exe` disappears.
+PID reuse/UID changes trigger a reread. No owner allowlist or privilege request is
+used to make an unknown state pass.
+
+## Findings
+
+| Rule | Condition |
+| --- | --- |
+| `RF-DELETED` | Missing configured target or previously baselined file |
+| `RF-FROZEN-CHANGED` | Frozen file hash, size, or mtime changed |
+| `RF-SQLITE-HEADER` | Expected SQLite magic lost |
+| `RF-INTEGRITY` | SQLite copy check did not return `ok` |
+| `RF-SHRINK` | Live database empty or below 50% of its baseline size |
+| `RF-ENTROPY` | First 4 KiB moved from below 7.0 to above 7.5 bits/byte |
+| `RF-MASS-CHANGE` | Folder changes exceed 20 files or 30%, over 10 new-extension files appear, or a new decrypt/recover/readme-text note appears |
+| `RF-MODE` | Any permission bits loosened relative to baseline |
+| `RF-FUTURE-MTIME` | Mtime ahead of the check clock |
+| `RF-DEFERRED` | More than 24 hours continuously deferred; one informational alert per episode |
+
+Renames that retain an inode retain the entropy comparison. A replacement written
+to a new inode/path cannot be reliably associated with the old file; deletion,
+extension, and mass-change findings still apply. These are evidence signals, not
+a malware diagnosis. Entropy is estimated from a sample, not the whole file.
+
+## State, privacy, and alerts
+
+State is under `$XDG_STATE_HOME/raftward` (default `~/.local/state/raftward`), mode
+0700. Files are created 0600 with `os.open`; no post-write chmod is used. Unsafe
+existing state permissions or symlinked parents are refused, not repaired.
+
+- `fp.key`: 32 random bytes used for HMAC-SHA256 identifiers (`fp:` plus 16 hex
+  characters). A missing key beside an existing baseline is an error.
+- `baseline.json`, `previous.json`, `last.json`: metadata and findings.
+- `history.jsonl`: at most 30 days and 4 MiB of recent metadata (older rows trimmed).
+- `accepts.jsonl`: review records with reason fingerprints, at most 4 MiB.
+- `targets.json`: optional CLI-managed targets; `deferred.json`: deferral episode;
+  `alerts.json`: hashed delivery receipts with a 24-hour dedupe period.
+
+Paths appear only locally. Recognized token-shaped substrings in local metadata
+are HMAC-redacted. Because arbitrary filenames and operator-supplied configuration
+are not universally recognizable as secrets, keep credentials out of target
+names and paths. File contents are never rendered or scanned for display.
+
+Critical findings alert during `check`. Other findings are available in reports;
+`report --send` explicitly delivers their aggregate summary. `alert_channels`
+accepts `stdout`, `slack`, `ntfy`, or `email`; an empty list means stdout. Network
+delivery is opt-in by configuring a non-stdout channel. Payloads contain rule IDs,
+counts, and severity only, and end with
+"run `raftward report` locally for details". They contain no hostname, paths,
+process arguments, or file content. Delivery is deduped for 24 hours and uses a
+five-second timeout. Redirects are not followed.
+
+Use environment-variable **names**, never inline credentials:
+`alert_slack_webhook_env`, `alert_ntfy_token_env`, `alert_smtp_password_env`.
+Other channel keys are `alert_ntfy_topic`, `alert_smtp_host`, `alert_smtp_port`,
+`alert_smtp_security` (`starttls`, `ssl`, or loopback-only `none`),
+`alert_smtp_username`, `alert_smtp_from`, and `alert_email`. HTTPS is required
+except on loopback; SMTP encryption is required off loopback. Errors never echo
+remote credential-bearing URLs.
+
+## Development and review
+
+```sh
+python3 -m pytest -q
+```
+
+Tests use a temporary HOME, fixture databases, and injected process listings.
+They do not inspect real application data. No timer is installed. See
+`REVIEW.md` for the independent acceptance report and remaining limits.