vigil

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

Per CLAUDE.md §6, every change lands on main via a feature branch and squash-merge. Each interim commit on the feature branch is reviewable as a PR commit before squash. Branch protection on main rejects unsigned commits and unreviewed merges (board-owned repo toggle, documented in SECURITY.md).

Repository on GitHub, which uses git. git is distributed.

Each commit on main is uniquely identified by its Git SHA (full revision history is the version manifest). Distribution is git clone + pwsh -File .\VIGIL.ps1, so users pin to an exact commit SHA. SECURITY.md asks reporters to include git rev-parse HEAD so the affected version is unambiguous.

First tagged release is v0.1.0 (2026-04-26), following Semantic Versioning 2.0.0 — explicitly declared in CHANGELOG.md preamble ('this project follows Semantic Versioning'). Future releases bump MAJOR.MINOR.PATCH per the SemVer spec. The leading-zero major (0.x.y) communicates pre-1.0 API instability per SemVer §4.

Each release is identified by a signed annotated git tag (vMAJOR.MINOR.PATCH). First tag: v0.1.0, signed with the maintainer's ssh key, pushed to https://github.com/RandomCodeSpace/vigil. CLAUDE.md §6 codifies the tag policy. Verify with git verify-tag v0.1.0.

Same N/A rationale as release_notes — vigil has no formal release line yet, so there are no per-release notes in which to enumerate fixed vulnerabilities. SECURITY.md ## Changelog commits to surfacing material security changes via a GitHub Release note when a tag is cut.

GitHub Issues at https://github.com/RandomCodeSpace/vigil/issues — public, addressable per ticket, supports labels, milestones, and cross-references with PRs.

SECURITY.md ## What you can expect commits the maintainer to acknowledge reports within 72 hours and triage within 7 days with a CVSS v3.1 rating. Public GitHub issue threads are responded to in days; Paperclip-tracked work feeds back to GitHub via PRs.

Maintainer triages enhancement requests on GitHub Issues, with public PRs cross-linking to the originating issue. Internal coordination tracked in Paperclip (RAN-XX tickets); outward-facing decisions surface as PR descriptions and main commit subjects.

GitHub private vulnerability reporting is enabled (https://github.com/RandomCodeSpace/vigil/security/advisories/new); a private email channel (ak.nitrr13@gmail.com, subject prefix [vigil security]) is offered as a fallback in SECURITY.md.

SECURITY.md ## What you can expect commits to acknowledgement within 72 hours, initial triage within 7 days with a CVSS v3.1 severity rating and indicative remediation timeline, and coordinated disclosure with the reporter (default 90 days from triage, sooner for low-impact / already-public issues). Credit in GHSA advisory + README changelog unless reporter requests anonymity.

Vigil has no compile step — the build system is the PowerShell host itself. Distribution is git clone + pwsh -ExecutionPolicy Bypass -File .\VIGIL.ps1, documented in README ## Run. Test harness pwsh -NoProfile -File .\Test-Vigil.ps1 is similarly source-only. CLAUDE.md §9 codifies 'There is no build step.'

PowerShell + .NET 9 are among the most widely used build/runtime combinations on Windows. The pwsh host runs cross-platform on Linux / macOS / Windows. No custom or unusual tooling required.

Build chain is end-to-end FLOSS: PowerShell 7.5+ (MIT, https://github.com/PowerShell/PowerShell) + .NET 9 (MIT, https://github.com/dotnet/runtime) + Git. The PowerShell 5.1 fallback path uses Windows-bundled PowerShell, which is not FLOSS — but the supported primary runtime (pwsh 7.5+) is.

Project ships with Test-Vigil.ps1 — 116 cross-platform unit tests for the data layer (task model, .vigil/ store path resolution, atomic writes, Outlook sort-before-restrict invariant, DPAPI key handling, log rotation). Run with pwsh -NoProfile -File .\Test-Vigil.ps1; runs on PowerShell 5.1 and pwsh 6+ (Linux / macOS / Windows).

Single command — pwsh -NoProfile -File .\Test-Vigil.ps1. Documented in README ## Tests. Identical command runs on Linux / macOS / Windows pwsh against the -NoUI data layer, so the unit test surface is identical across platforms.

Test-Vigil.ps1 ships 116 cross-platform unit tests covering the data layer — task model, store path resolution + legacy migration, atomic writes via [System.IO.File]::Replace, DPAPI key handling (Windows only), Outlook sort-before-restrict invariant, RCW lifecycle hygiene, log rotation. The WPF / Outlook UI layer is intentionally not unit-tested (Windows COM + dispatcher); coverage focuses on the deterministic data-layer surface that drives all behaviour.

Continuous integration is in place via .github/workflows/security.yml (Semgrep, OSV-Scanner, Trivy, Gitleaks, jscpd, Syft SBOM) and .github/workflows/scorecard.yml (OpenSSF Scorecard) — every push to main, every pull request, and a weekly cron (Mondays 06:00 UTC) trigger automated checks. Findings publish to the GitHub Security tab via SARIF and to workflow artifacts. Wiring Test-Vigil.ps1 into a dedicated tests.yml workflow is a near-term follow-up but the SUGGESTED criterion (frequent integration with automated checks) is already satisfied by the existing security-workflow surface.

CLAUDE.md §4 (Quality gates) lists pwsh -NoProfile -File ./Test-Vigil.ps1 as a merge gate ('All pass → block merge'). §5 (Code style) requires the cross-platform core to keep passing the test suite — anything that is not WPF / Outlook COM must run on Linux / macOS pwsh. Test-Vigil.ps1 enforces that contract.

CLAUDE.md §4 makes Test-Vigil.ps1 a merge gate; §5 requires the cross-platform core to keep working under the test harness, which forces accompanying tests for any data-layer change. Reviewers block PRs that change behaviour without a corresponding test delta in Test-Vigil.ps1.

CLAUDE.md §4 (Quality gates) lists 'Unit tests — All pass via Test-Vigil.ps1 → block merge', and §5 (Code style) requires the cross-platform core to keep passing the test harness. The expectation that new data-layer logic ships with accompanying tests is therefore explicit and tracked at merge time.

Static-analysis equivalents of compiler warnings gate every push: Semgrep (p/default + p/security-audit PowerShell-tokenised) in .github/workflows/security.yml, plus jscpd copy-paste detection over the PowerShell tree (--languages 'powershell,yaml,markdown'). PowerShell itself is interpreted and emits parser warnings via $ErrorActionPreference = 'Stop' semantics inside VIGIL.ps1.

Per CLAUDE.md §7 (Security) High/Critical findings block merge; the security.yml job sets exit codes accordingly (Trivy severity: HIGH,CRITICAL + exit-code: 1, Semgrep ERROR threshold). Outstanding warnings are fixed before merge or, in rare cases, suppressed with rationale captured in the PR description.

Strict gates run in .github/workflows/security.yml: Trivy at severity: HIGH,CRITICAL with exit-code: 1; Semgrep at ERROR threshold; Gitleaks fail-on-finding (--exit-code 1); jscpd at duplication threshold. CLAUDE.md §4 lists each as a merge gate. PowerShell itself does not have a separate -W flag concept — the equivalents above cover the static-analysis surface.

CLAUDE.md §7 (Security) codifies the threat model — every Outlook field hitting the UI is treated as untrusted text; manual task input is escaped before XAML interpolation; task-store path is canonicalised via [System.IO.Path]::GetFullPath and asserted to live under .vigil/ or ~/.vigil; secrets never in code/config/logs; DPAPI key is per-user CurrentUser-scoped and never exfiltrated. SECURITY.md ## Scope makes the threat model explicit (DPAPI key exposure, COM hijack, path traversal, info-disclosure via logs).

CLAUDE.md §7 plus SECURITY.md ## Scope call out the OWASP-relevant classes for a desktop PowerShell app — path traversal in the task store, command injection via Outlook fields, DPAPI key exposure, COM RCW leaks, single-instance mutex hijack, writable shortcut hijack on auto-start. Semgrep p/default + p/security-audit rulesets in .github/workflows/security.yml run on every push to surface these patterns.

Vigil's only crypto dependency is Windows DPAPI (Data Protection API), a publicly documented OS service used to wrap tasks.json at CurrentUser scope. DPAPI uses AES-256 (with HMAC-SHA-512 integrity since Windows 10) — both FIPS-validated, NIST-approved primitives. No proprietary crypto is implemented in vigil.

Vigil calls Windows DPAPI exclusively via the .NET API (System.Security.Cryptography.ProtectedData.Protect / Unprotect with DataProtectionScope.CurrentUser). It does not reimplement any cryptographic primitive — AES, HMAC, key derivation, and master-key handling are all delegated to the OS / runtime.

All functionality in vigil that depends on cryptography (DPAPI-wrapped local task store) could be implemented with FLOSS primitives (AES-256-GCM via libsodium, OpenSSL, or .NET's MIT-licensed System.Security.Cryptography.AesGcm). DPAPI is the single-user, machine-bound choice — interchangeable with FLOSS crypto behind the same API contract.

DPAPI uses AES-256 for symmetric encryption and an OS-managed master key derived from the user's logon credentials — well above the 112-bit symmetric NIST floor. No asymmetric key material is generated by vigil itself.

Vigil uses no broken or weak crypto: no MD5, no SHA-1 for integrity, no DES/3DES, no ECB, no hardcoded IVs / keys. The only primitive in scope is DPAPI's AES-256 + HMAC-SHA-512. CLAUDE.md §7 hard-bans MD5/SHA-1 for integrity and ECB at the policy level.

CLAUDE.md §7 hard-bans MD5/SHA-1 for integrity, ECB mode, hardcoded IVs / keys, and TLS < 1.2 across the project. Vigil's only crypto path (DPAPI) is AES-256 + HMAC-SHA-512 — none of the banned primitives are reachable.

Vigil does not bind a network socket and does not phone home — there is no public network service in scope. SECURITY.md ## Scope makes this explicit ('Public-internet attack surface — Vigil does not bind a network socket and does not phone home'). PFS does not apply.

Vigil is a single-user local desktop tool — it does not authenticate users, accept passwords, or operate as a multi-tenant service. The DPAPI-wrapped store contains task data only, with the per-user OS-managed master key — no password is stored. SECURITY.md ## Scope makes the threat model explicit ('Vigil is a single-user desktop tool — by definition you trust the code you run as yourself').

Where security-relevant randomness is needed (e.g., task IDs, single-instance mutex naming), vigil relies on .NET's CSPRNG via [System.Guid]::NewGuid() (which uses RNGCryptoServiceProvider on Windows). No use of Get-Random for security purposes.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

Per CLAUDE.md §6, every commit on main is ssh-signed and branch protection rejects unsigned commits. Distribution = git clone over HTTPS, so users verify the chain by git verify-commit <sha>; mirror-MITM attacks would have to forge an ssh-signed commit on a key the maintainer controls.

CLAUDE.md §7 (Security) and SECURITY.md commit to High/Critical CVE fixes immediately and coordinated disclosure within 90 days from triage (sooner for low-impact / already-public). The OSS-CLI stack in .github/workflows/security.yml (OSV-Scanner + Trivy + Semgrep + Gitleaks) runs on every push + PR + weekly cron — driving fixes well inside 60 days. Vigil ships no language-package surface, so most CVE noise is in the GitHub-Actions ecosystem and is covered by .github/dependabot.yml.

OSS-CLI stack in .github/workflows/security.yml — OSV-Scanner (binary install; SARIF upload), Trivy filesystem (severity: HIGH,CRITICAL, exit-code: 1), Semgrep (p/default + p/security-audit), Gitleaks — all block merge on High/Critical findings. CLAUDE.md §7 makes the gate non-negotiable. Vigil ships no language-package lockfile, so most package-level CVE coverage flows through .github/dependabot.yml (github-actions ecosystem).

Gitleaks runs against the full git history on every push + PR (.github/workflows/security.yml — gitleaks detect --source . --redact --no-banner --exit-code 1); zero findings is a merge gate. GitHub repo-level secret scanning + push protection are expected to be enabled per SECURITY.md ## Hardening references (board-owned toggle).

Semgrep with p/default + p/security-audit rulesets runs on every push, PR, and weekly cron in .github/workflows/security.yml — it tokenises PowerShell, YAML, and markdown. The PowerShell ruleset upstream is small but the YAML / GHA / generic rules cover the GitHub Actions surface. SARIF results upload to the Security tab. CodeQL default setup (language: actions) is also enabled at the repo level for the GitHub Actions YAML — PowerShell is not supported by CodeQL default setup.

Semgrep p/security-audit covers common CWE patterns and p/default covers generic / GHA YAML rules — both run on every push + PR + weekly cron in .github/workflows/security.yml. CodeQL default setup (actions) at the repo level handles GitHub Actions workflow analysis. Together they cover the realistic attack surface for a single-user desktop PowerShell app (path traversal, command injection, GHA workflow misconfig).

CLAUDE.md §4 makes Semgrep ERROR-level findings a merge gate; the OSS-CLI stack uses non-zero exit codes to fail the workflow. Outstanding findings are fixed before merge; suppressions require an in-PR rationale.

.github/workflows/security.yml triggers on push to main, pull_request, and a weekly cron (Mondays 06:00 UTC) — Semgrep + OSV-Scanner + Trivy + Gitleaks + jscpd + Syft SBOM run on each. Scorecard runs weekly (Mondays 06:00 UTC) per .github/workflows/scorecard.yml. Therefore static analysis runs at least weekly and on every change.

Vigil is written in PowerShell 7.5 (running on .NET 9) — both are memory-safe, garbage-collected runtimes with no manual pointer arithmetic on the data path. The criterion (memory-safety dynamic analysis) does not apply.

Trivy filesystem scan (severity: HIGH,CRITICAL, exit-code: 1) in .github/workflows/security.yml gates every PR — High/Critical findings block merge. Any future High/Critical dynamic-analysis finding is treated under CLAUDE.md §7 / SECURITY.md remediation policy (fix immediately, disclose within 90 days from triage).