Vigil

WARNING! Vigil is under development. Use at your own risk

Endpoint defense for Windows and Linux.

Vigil watches live network and process activity, scores suspicious behaviour, shows the process and connection context behind each alert, and can take reversible containment actions when something needs to be stopped.

The active support scope is Windows and Linux only. See docs/SUPPORTED-PLATFORMS.md for the support contract and startup-safety rule.

---

Documentation

• User guide — released functionality and operator workflows
• Response rules — YAML syntax, advisory-aware predicates, and example rule patterns
• Supported platforms — Windows/Linux support contract
• Security policy — vulnerability reporting and security contacts
• OpenSSF Best Practices controls — repository controls and maintainer settings
• Codebase inventory — repositories that are part of Vigil
• Advisory source compliance — attribution, caching, and reuse rules for public vulnerability and advisory feeds
• Bundled YARA ruleset contract — source-selection, redistribution, provenance, and signed-update rules for future community rule packs

---

Download the latest build

• Windows installer
• Linux AppImage
• Signed update manifest
• Manifest signature
• GHCR Linux package image: ghcr.io/YMRYMR/vigil

The latest-release links are refreshed by the release pipeline after a merged master change finishes CI and the tag-driven publishing workflow completes.

The GHCR image tracks the latest released Linux AppImage as a container package:

docker pull ghcr.io/YMRYMR/vigil:latest

Each release asset is published with a GitHub artifact attestation. Verify a downloaded file with:

gh attestation verify PATH/TO/FILE -R YMRYMR/vigil

The signed update manifest is the trust anchor for Vigil's update channel. It lists release assets and SHA-256 digests, then gets signed with the embedded Ed25519 public key. Verify it offline with:

vigil --verify-update-manifest Vigil-latest-update-manifest.json Vigil-latest-update-manifest.json.sig

---

Local YARA Rule Intake

Phase 20's first safe foundation is integrity-checked local YARA rule intake. Operators can stage .yar or .yara files under the Vigil data directory in yara-rules/, with a matching .sha256 sidecar beside each rule file.

Verify those local rule files, record provenance, and mirror the parsed rule catalog into Vigil's protected local state with:

vigil --yara-rule-status

This command does not run YARA scans yet. It verifies trusted intake for future process and memory scanning work, mirrors normalized per-file and per-rule metadata into the local SQLite state database, and fails closed on missing or mismatched sidecars.

The future bundled community-rules path also has an explicit compliance and signed-update contract in docs/YARA-RULESET-COMPLIANCE.md.

---

What Vigil does

Detect and surface suspicious activity

• Sub-100 ms detection on Windows via ETW and on Linux via eBPF when available.
• Polling fallback when the realtime backend is unavailable.
• Multi-signal threat scoring across behaviour, reputation, persistence, and execution context.
• Passive persistence and timing signals such as registry autoruns, beaconing, pre-login activity, long-lived connections, and DGA-like hostnames.
• Offline enrichment with local blocklists, geolocation, ASN data, reverse DNS, and file-drop correlation.

Help investigate what is happening

• Full ancestor process tree up to 8 levels deep.
• Process-first GUI with Activity, Alerts, Settings, Help, and a detailed Inspector.
• Clickable notifications and tray workflow for fast triage.
• Boot-time service mode for monitoring before login on supported platforms.

Protect and contain the machine

• Active response on Windows and Linux: kill a live TCP connection, suspend/resume a process, block a remote IP, block a process by executable path, or isolate the machine.
• Containment safety rails: confirmation prompts, countdowns for temporary blocks, inline unblock controls, and break-glass recovery.
• Policy-driven automation: user-defined response rules, scheduled lockdown, allowlist-only mode, and threshold escalation.

Preserve trust, evidence, and operator control

• Forensic capture on high-confidence alerts where supported, including PCAP, process dump, TLS sidecar metadata, and provenance manifests.
• Tamper-evident local state for policy, generated state, audit logs, and update manifests.
• Daily rolling logs and audit trail for alerts, actions, integrity events, and other security-relevant changes.
• Privilege-aware UX that shows when deeper visibility or containment requires elevation.

---

Public advisory and vulnerability intelligence

Vigil treats public vulnerability and advisory matches conservatively. A match means Vigil found a plausible link between local software and a public CVE or advisory record from its local source cache; it does not prove exploitation or compromise.

Offline import examples:

vigil --import-nvd-snapshot nvdcve-page-1.json nvdcve-page-2.json
vigil --import-nvd-change-history nvdcvehistory-page-1.json
vigil --import-euvd euvd-export.json
vigil --import-jvn jvn-export.json jvndbrss.xml
vigil --import-ncsc ncsc-feed.xml ncsc-mirror.json
vigil --import-bsi certbund-feed.xml bsi-advisories.json

Live NVD sync:

vigil --sync-nvd
vigil --sync-nvd-change-history
vigil --advisory-cache-status
vigil --advisory-change-history-status

After the protected software inventory snapshot and protected advisory cache both exist locally, print explainable product-to-advisory matches with:

vigil --advisory-match-status

Use docs/RESPONSE-RULES.md together with response-rules.example.yaml when you want to turn those high-confidence advisory matches into conservative operator-managed response rules.

Those advisory-aware predicates stay intentionally narrow today. Mitigation guidance counts only when the protected advisory cache preserves non-empty mitigation text or an explicit remediation-tagged reference such as Mitigation, Remediation, Fix, Patch, Update, Upgrade, Workaround, Guidance, or Solution. Vendor guidance counts only when that same tagged reference is also marked as vendor-authored material such as Vendor Advisory, Vendor Bulletin, Vendor Notice, Vendor Mitigation, or Vendor Remediation. Public-internet exposure counts only for a current LISTEN socket bound to an obviously globally routable local IP. Fixed-version-only tokens do not count as operator guidance.

Use --sync-nvd --force only when you need to override the normal 2-hour minimum interval. Provide an API key via VIGIL_NVD_API_KEY if the deployment needs higher NVD API headroom.

The standalone inventory helper can inspect local Windows/Linux software metadata without touching Vigil's startup path:

vigil_inventory

Its JSON output includes normalized product and vendor hints such as product_key, product_aliases, vendor_key, and vendor_aliases so later matching stays explainable and conservative.

---

Installation

Windows

1. Download the Windows installer from the latest release.
2. Run the installer. By default it installs for the current user, creates a Start Menu shortcut, and enables Vigil at login.
3. For before-login monitoring, choose an all-users install or run the service install command from an elevated shell.

ETW-backed realtime monitoring requires Administrator rights. Without elevation, Vigil falls back to polling.

Linux

1. Download the Linux AppImage from the latest release.
2. Make it executable:

chmod +x Vigil-*.AppImage

3. Launch it from the desktop or terminal.

Linux active response requires root or the required Linux capabilities, depending on the action.

---

Building from source

Prerequisite: Rust stable 1.75+.

git clone https://github.com/YMRYMR/vigil.git
cd vigil
cargo build --release

The binary is written to target/release/vigil or target/release/vigil.exe.

Using just:

just build
just release
just test
just lint
just install
just ci

Windows icon embedding

build.rs generates a multi-size .ico file and embeds it via winres. This requires the Windows SDK rc.exe or llvm-rc. If neither is present, the build still succeeds without the custom taskbar icon.

---

Configuration

Settings are stored in vigil.json in the per-user Vigil data directory and are editable in-app through Settings.

Common settings include:

Setting	Default	Description
alert_threshold	3	Minimum score to trigger an alert