================================================================================ TraceGuard 1.0.0 Techlosoft "Privacy Eraser" product line -- Team variant Fleet-wide privacy posture reporting ================================================================================ WHAT IT IS -------------------------------------------------------------------------------- TraceGuard answers one question that none of its siblings answer: "Is my whole team compliant with our privacy policy, and who isn't?" PrivacySweep securely overwrites a named path. EraseProof runs policy-driven recurring erasure with a ledger. CleanVault scans one machine's browser and app traces. All three act on a SINGLE machine. TraceGuard is the rollup layer. Each machine produces a scan report; TraceGuard ingests all of those reports, evaluates every machine against a WRITTEN POLICY, and prints a compliance table plus a fleet summary -- which machines pass, which fail, exactly which rule each one broke, and how much data the fleet is exposing in total. TRACEGUARD ONLY REPORTS. IT NEVER DELETES ANYTHING. -------------------------------------------------------------------------------- This is a deliberate design decision, not an omission. TraceGuard opens files for reading only. It never writes to, truncates, renames, chmods, or unlinks anything inside a scanned home directory. The only files it ever creates are the report file you name with --out and whatever you redirect stdout into. Remediation is intentionally left to the other tools in the line: - CleanVault -- clean one machine's traces interactively - EraseProof -- policy-driven recurring erasure with an audit ledger - PrivacySweep-- secure overwrite of a specific path Keeping the reporter and the eraser separate means an audit can never destroy the evidence it is auditing, and a compliance report can be produced by someone who does not have destructive rights on the fleet. REPORTS ARE COLLECTED MANUALLY. THERE IS NO NETWORK. -------------------------------------------------------------------------------- TraceGuard has no agent, no daemon, no server and no network code of any kind. It does not open sockets. The intended workflow is: 1. On each machine, someone runs: traceguard scan --home ~ --machine laptop-07 --out laptop-07.json 2. The resulting JSON files are collected into one directory by whatever means you already trust -- a share, a ticket attachment, a USB stick, scp, your MDM's file collection, git. 3. On the auditing machine: traceguard audit --dir ./reports --policy policy.json That manual hop is the current shipping reality. It is honest about what the tool does rather than implying a fleet management backend that does not exist. COMMANDS -------------------------------------------------------------------------------- traceguard scan --home --machine [--out ] [--json] traceguard audit [more.json ...] [--dir ] --policy [--fail-on low|medium|high] [--json] traceguard policy --example traceguard help | -h | --help scan Measures one machine's privacy traces beneath --home. For each built-in trace category it records: - the number of files - the total bytes - the age in days of the OLDEST artifact (and its relative path) Every path is resolved relative to --home, so scans are reproducible and testable against a synthetic tree. Without --json it prints a summary table; with --json it prints the machine-readable report. --out writes the JSON report to a file (use "-" for stdout). audit Ingests one or many reports (positional paths and/or every *.json in --dir, de-duplicated), evaluates each against the policy, and prints: - a per-machine compliance table (verdict, violation count, worst severity, exposed bytes, exposed files) - the full violation list, one line per broken rule per machine - any reports that had to be skipped, with the reason - a fleet summary: machines audited, passed, failed, skipped, total violations, total exposed bytes, and the most commonly violated rule policy --example Prints a real, runnable example policy to stdout so you can start from something that works instead of from a blank file. TRACE CATEGORIES (built in, fixed in 1.0) -------------------------------------------------------------------------------- browser_cache cached page assets written by browsers cookies cookie jars and their write-ahead logs browsing_history visited-URL databases saved_sessions restorable tab/session state thumbnail_cache generated image/document thumbnails recent_documents recently-opened document trails crash_dumps crash reports and minidumps temp_files per-user temporary scratch files Each category is a fixed list of glob patterns resolved under --home, covering common Linux, macOS and Windows profile layouts. A file is counted at most once, by the FIRST category whose pattern claims it, so the per-category numbers always add up to the reported total with no double counting. POLICY FORMAT -------------------------------------------------------------------------------- A policy is a JSON object with a name and a list of rules: { "name": "Techlosoft Team Baseline", "description": "Baseline privacy posture for team laptops.", "rules": [ { "id": "cache-size", "category": "browser_cache", "type": "max_bytes", "limit": 50000, "severity": "high" }, { "id": "history-age", "category": "browsing_history", "type": "max_age_days", "limit": 90, "severity": "high" }, { "id": "no-crash-dumps", "category": "crash_dumps", "type": "forbidden", "severity": "high" }, { "id": "temp-size", "category": "temp_files", "type": "max_bytes", "limit": 100000, "severity": "medium" }, { "id": "cookie-count", "category": "cookies", "type": "max_files", "limit": 3, "severity": "low" } ] } Rule types: max_age_days no artifact in the category may be older than days max_bytes the category must not exceed bytes max_files the category must not exceed files forbidden the category must be entirely absent (limit ignored) Limits are inclusive: a category of exactly bytes PASSES; +1 fails. Same for max_files and max_age_days. Severities: low, medium, high. "id" is optional -- if omitted it is generated as "/". "severity" defaults to high if omitted. PASS / FAIL AND --fail-on -------------------------------------------------------------------------------- A machine FAILS if it violates any rule whose severity is at or above the --fail-on threshold. Default is high. --fail-on high (default) only high-severity violations fail a machine --fail-on medium medium and high fail --fail-on low any violation at all fails Violations below the threshold are still reported in full -- they just don't flip the verdict. This lets one policy serve both a strict gate and an informational sweep. EXIT CODES -------------------------------------------------------------------------------- 0 success; for audit, every machine passed the policy 1 usage error, unreadable input, malformed policy, or no usable reports 2 audit completed normally and at least one machine FAILED the policy Exit 2 is separate from exit 1 on purpose: a non-compliant fleet is a valid result, not a tool error, and CI should be able to tell the two apart. HOW AGE IS CALCULATED -------------------------------------------------------------------------------- Age comes from the file's modification time. Elapsed time is divided by 24 hours and ROUNDED TO THE NEAREST WHOLE DAY. Rounding rather than truncating is deliberate: a daylight-saving shift or a few seconds of scan latency would otherwise report a file created exactly 400 days ago as 399 days old. The reported age for a category is the age of its OLDEST artifact, which is the number a "nothing older than N days" rule actually cares about. ERROR AND EDGE-CASE HANDLING (explicit choices) -------------------------------------------------------------------------------- Corrupt or foreign report among good ones Skipped and listed under SKIPPED REPORTS with a specific reason (malformed JSON, empty file, missing "machine" field, produced by another tool, format version newer than this build). All other machines are still audited normally. One bad file never aborts a fleet audit. No usable reports at all Error to stderr, exit 1. Empty policy (no rules, or no "rules" key) Not an error. Every machine passes by definition, and the output says so explicitly with a "policy has no active rules" note. Exit 0. Policy rule naming an UNKNOWN category Warning printed, that rule is dropped, and the remaining rules are still enforced. Rationale: a policy written for a newer catalog should still audit whatever this build understands rather than refusing to run. Policy rule with an unknown TYPE or unknown SEVERITY, or a negative limit Hard error, exit 1. Unlike an unknown category, these are typos that would silently weaken the policy, so they are refused rather than ignored. Report missing a category the policy mentions Treated as "not measured" -- no violation is raised for it. Symbolic links Never followed and never counted. Only regular files are measured, so a symlink out of the home tree cannot inflate or redirect a scan. Unreadable subdirectory during a scan Skipped; the rest of the scan continues. Duplicate report paths (positional plus --dir) De-duplicated by absolute path; each machine is counted once. WHAT IS *NOT* IMPLEMENTED -------------------------------------------------------------------------------- Being blunt about the boundaries: - No deletion, shredding, quarantining or remediation of any kind. - No network. No agents, no daemon, no push, no pull, no API, no TLS. Reports are files you move around yourself. - No historical trending. Each audit is a snapshot of the reports you hand it. TraceGuard does not store previous runs and cannot tell you whether the fleet improved since last week. - No scheduling. There is no cron integration, no built-in timer, no daemon mode. Run it from your own scheduler if you want it periodically. - No alerting. No email, Slack, webhook or ticket creation. Exit code 2 plus --json is the integration surface. - No report signing or tamper-evidence. A report is plain JSON and anyone who can edit the file can make a machine look compliant. Do not treat reports from untrusted hands as authoritative. - No custom/user-defined trace categories. The catalog is fixed in 1.0; a policy can only constrain the eight built-in categories. - No per-machine or per-group policy overrides. One policy applies to the whole set of reports in a single audit run. - No file content inspection. TraceGuard measures counts, sizes and mtimes. It never reads what is inside a cookie jar or a history database. - No process/registry/network-connection scanning -- filesystem artifacts only. - No deduplication of the same machine reported twice under different names. ROADMAP -------------------------------------------------------------------------------- - Agents reporting over the network, so reports arrive without a manual hop. - Historical fleet trending: keep prior audits and show whether posture is improving or degrading, per machine and per rule. - Scheduled audits with a built-in runner. - Alerting: notify on newly failing machines and on regressions, rather than requiring someone to read the exit code. - Signed / tamper-evident reports so a machine cannot forge its own compliance, including a verify subcommand. BUILDING -------------------------------------------------------------------------------- Go standard library only. No third-party dependencies, no network access needed to build: go build -o traceguard . Cross-compiled binaries in dist/: traceguard-linux-amd64 traceguard-darwin-amd64 traceguard-darwin-arm64 traceguard-windows-amd64.exe WORKED EXAMPLE -------------------------------------------------------------------------------- $ traceguard scan --home ~ --machine laptop-07 --out reports/laptop-07.json TraceGuard scan - machine "laptop-07" ... CATEGORY FILES BYTES SIZE OLDEST(d) browser_cache 6 120000 117.2 KiB 6 cookies 2 2000 2.0 KiB 4 ... $ traceguard policy --example > policy.json $ traceguard audit --dir reports --policy policy.json MACHINE VERDICT VIOLATIONS WORST EXPOSED FILES alpha PASS 0 - 36.9 KiB 15 bravo FAIL 2 high 275.2 KiB 16 charlie FAIL 2 high 149.7 KiB 12 delta FAIL 2 high 232.7 KiB 14 echo PASS 1 low 37.4 KiB 13 VIOLATIONS bravo [high] cache-size browser_cache max_bytes ... ... FLEET SUMMARY Machines audited: 5 Passed: 2 Failed: 3 Total exposed bytes: 749500 (731.9 KiB) Most violated rule: temp-size (temp_files max_bytes) - 3 machine(s) Fleet status: NON-COMPLIANT ================================================================================