Autonomous Vigilance Engine for Reconnaissance & Yield
APT detection infrastructure. Built for threat hunters, not dashboards.
AVERY is a self-hosted security operations platform built for the detection of advanced persistent threats operating under active evasion. The platform ingests full-fidelity telemetry across network, host, and passive sensor layers simultaneously, applies behavioral correlation in real time, and positions threat intelligence at the detection layer rather than downstream as an enrichment step. All inter-service communication runs over an authenticated zero-trust overlay. Nothing listens on a public interface.
This repository is the automation layer that built and currently operates the production deployment.
The problem with how most organizations detect advanced adversaries is not the quality of individual tools. It is how those tools are connected, or more precisely, how the assumptions embedded in their architecture limit what they can find.
Detection stacks built around signature matching assume that the adversary will behave in ways consistent with previously catalogued operations. Threshold-based anomaly detection assumes that malicious activity will differ statistically from baseline in ways that are both measurable and distinguishable from legitimate variation. These assumptions hold reasonably well against unsophisticated threats. Against a well-resourced actor conducting a targeted operation, they represent the floor the adversary was designed to stay above.
APT campaigns are defined by deliberate operational security that is specifically calibrated to the capabilities of the defender. Infrastructure is rotated on schedules that outpace indicator feeds. TTPs are selected and modified to avoid known behavioral signatures. Dwell time is managed to remain within the noise floor of anomaly detection systems. Lateral movement is paced to avoid generating the kind of statistical variance that triggers alerts. The adversary is not trying to avoid being seen by your tools. They are trying to avoid being seen by your analysts, and the distinction matters, because most tools surface what they were designed to look for, not what is actually present.
The result is a structural gap between what conventional detection architectures are capable of finding and what a patient, well-resourced adversary is capable of concealing. That gap is not a configuration problem. It is not solved by adding more data sources or tuning existing rules. It reflects a category difference between the detection model most platforms implement and the threat model that advanced adversaries actually represent.
AVERY is built around a different detection model. The operational assumption is that the adversary has already read the relevant threat intelligence literature, is aware of common detection methods, and has made explicit decisions about which signal categories to suppress. Under that assumption, detection requires looking for behavioral patterns that persist even under deliberate evasion patterns that the adversary cannot easily suppress without changing the fundamental nature of their operation. What those patterns are, and how they are identified, is not documented here.
Four functional layers. The implementation of each is not documented publicly.
+------------------------------------------------------------------+
| TELEMETRY COLLECTION |
| |
| Network Edge . Host-Based Agents . Passive Sensors |
| |
| Simultaneous ingestion across all visibility layers. No |
| single telemetry source is required for detection coverage. |
| Suppressing or losing any individual source degrades |
| fidelity but does not eliminate detection capability. |
| Telemetry is normalized and timestamped at collection. |
+------------------------------+-----------------------------------+
|
+------------------------------v-----------------------------------+
| |
| BEHAVIORAL CORRELATION ENGINE |
| |
| Real-time analysis across the full telemetry stream. |
| Detections are confidence-weighted and mapped to MITRE |
| ATT&CK. The correlation model is tuned for behavioral |
| patterns consistent with known APT operational profiles. |
| Signatures and static thresholds are not the primary |
| detection mechanism. |
| |
+------------+---------------------------+--------------------------+
| |
+------------v-----------+ +----------v-----------+
| | | |
| THREAT INTELLIGENCE | | ORCHESTRATION & |
| INTEGRATION | | RESPONSE |
| | | |
| Structured CTI with | | Workflow engine |
| full indicator | | with configurable |
| lifecycle management.| | autonomy spectrum. |
| Correlation runs | | Alert delivery |
| against live | | with ATT&CK |
| telemetry — not | | context and |
| queued alerts. | | confidence |
| Campaign tracking | | scoring. Response |
| and infrastructure | | from assisted to |
| attribution across | | fully automated |
| the full indicator | | per environment |
| lifecycle. | | and policy. |
+------------------------+ +----------------------+
All communication runs over an authenticated zero-trust
overlay. No public listeners. No host-network firewall
rules protecting inter-service communication — the
network path does not exist without explicit overlay
provisioning. The attack surface is bounded by mesh
membership, not access control list accuracy.
On behavioral signals versus indicators
Indicators of compromise are artifacts. They describe what was left behind by a specific tool or operation at a specific point in time. An adversary who rotates infrastructure, modifies tooling, and operates with awareness of the public indicator ecosystem can suppress most indicator-based detection with relatively low operational cost. The indicator becomes stale faster than the threat actor changes behavior.
Behavioral detection operates on a different substrate. The patterns of interest are not artifacts of specific tools but properties of the operation itself, how an implant communicates relative to the surrounding traffic baseline, how a compromised host's process tree evolves over time, how network sessions initiated by a persistent access mechanism differ from those initiated by legitimate users doing similar things. These patterns are harder to suppress because suppressing them requires changing the fundamental mechanics of the operation, not just swapping a binary or rotating an IP.
The practical implication is that behavioral detection requires significantly more telemetry depth and a more complex correlation model than indicator matching. The tradeoff is worthwhile. An indicator match tells you something was present. A behavioral detection tells you something is happening.
On telemetry coverage
Single-source telemetry creates single-source blind spots. An adversary who identifies the collection mechanism and operates outside its visibility has effectively negated the detection capability without triggering any alert. AVERY collects simultaneously across network metadata, full session data, host telemetry, and passive sensor feeds. The specific coverage provided by each layer complements rather than duplicates the others, and the correlation engine is designed to operate across all layers simultaneously. Detection logic that depends on any single layer is explicitly avoided.
This has operational implications beyond detection quality. When one telemetry source is unavailable, whether due to infrastructure issues, deliberate suppression, or adversary action — detection capability degrades gracefully rather than failing completely. The correlation model accounts for missing data sources rather than assuming all sources are always present.
On intelligence integration
There is a meaningful architectural distinction between threat intelligence that enriches alerts after they fire and threat intelligence that informs what gets detected in the first place. Most platforms implement the former. The intelligence feed is consulted when an alert is generated, additional context is appended, and the analyst receives a richer notification. This is useful for triage and investigation. It does not change what was detected or whether it was detected.
AVERY implements the latter. Intelligence context, current threat actor infrastructure, active campaign indicators, behavioral profiles derived from reported operations is maintained continuously and integrated into the correlation process before detection decisions are made. An alert is generated with its intelligence context already incorporated, not appended. The distinction matters most in the early stages of an intrusion, when the signals are weakest and the enrichment-after-the-fact model is least helpful.
On response autonomy
Automated response in security operations is not a binary capability. The appropriate level of automation depends on the environment, the confidence of the detection, the reversibility of the response action, and the operational risk tolerance of the organization. A response action that is appropriate for a high-confidence detection in an isolated test environment may be entirely inappropriate for a medium-confidence detection in a production financial system.
AVERY's orchestration layer is designed to support the full autonomy spectrum without privileging any particular point on it. The threshold between assisted and automated response is a policy parameter, not an architectural constraint. The platform does not assume that automation is always better or that human review is always necessary. It assumes that the right answer depends on context, and makes the context available for the decision.
The production deployment runs continuously without manual intervention under normal conditions. A health monitoring layer checks every service on five-minute intervals, tracks state transitions, and fires Slack notifications on failures and recoveries with cooldown logic to suppress redundant alerts during extended outages. The first failure event and every recovery are always notified regardless of cooldown state.
Container resource management is handled by a per-minute watchdog that evaluates memory utilization across the full service stack. When utilization reaches 80% of a container's configured limit, the watchdog triggers a graceful restart and notification before any hard resource cap engages. This approach avoids the abrupt process terminations that occur when containers hit hard limits, which in stateful services can cause data loss and require manual recovery. The 80% threshold was selected to provide meaningful advance warning while still allowing normal utilization peaks to clear without intervention.
Host-based scanning runs daily at the lowest available CPU and IO scheduling priority using nice -n 19 and ionice -c 3. Scan scope is explicitly bounded to filesystem locations with documented historical relevance to post-exploitation activity per CISA guidance. Container volumes, package repositories, and high-throughput data directories are excluded. All match events are structured as JSONL and routed through the standard alert pipeline. The scanner does not impact detection stack performance under normal conditions.
Every automation script in this repository is idempotent and rollback-capable. None of it is theoretical. Everything runs against the production deployment.
AVERY/
|
+-- wazuh/
| +-- setup-syslog-listener.sh # Overlay-scoped syslog ingestion setup
| +-- install-rules.sh # Idempotent detection rule installer
| +-- integrations/
| +-- custom-slack.py # ATT&CK-enriched structured alert delivery
|
+-- agents/
| +-- avery-telemetry.sh # Network edge telemetry agent (POSIX sh)
|
+-- monitor/
| +-- soc_monitor.sh # Stack health monitor with state tracking
| +-- shuffle_watchdog.sh # Container memory watchdog
| +-- avery_yara_scan.sh # Scheduled host scanner
|
+-- config/
| +-- .env.example # Required environment variables
|
+-- docs/
+-- VISION.md # Research direction
+-- assets/
+-- avery-banner.svg
Detects the overlay network interface and assigned address at runtime. Injects a scoped <remote> block into the detection engine configuration, restricting the syslog listener to the overlay network address space. Restarts the service and validates listener state post-restart. Marker string prevents duplicate injection on re-runs.
sudo bash wazuh/setup-syslog-listener.shInstalls custom MITRE ATT&CK-mapped detection rules against a live Wazuh deployment. Before touching any file, generates a timestamped rollback script. trap ERR invokes rollback automatically on any failure, the detection engine returns to its prior state without manual intervention. Idempotency markers prevent duplicate rule injection across re-runs. Existing configuration state is preserved; nothing is overwritten.
sudo bash wazuh/install-rules.shCustom Wazuh integration replacing flat-text default notifications with structured Slack Block Kit messages. Every notification carries: severity level with visual encoding, rule description, agent identity, UTC timestamp, and MITRE ATT&CK tactic and technique identifiers where the triggering rule provides them. Webhook URL and minimum severity threshold are environment-variable driven — no credentials in code.
POSIX sh with no dependencies beyond nc. Designed for constrained environments including OpenWRT. Ships structured syslog telemetry over the overlay network to the detection engine on a configurable interval. The agent is intentionally minimal — anything that can fail, break, or require maintenance on a network edge device has been removed.
scp agents/avery-telemetry.sh YOUR_USER@<router-ip>:YOUR_DEPLOY_PATH/avery-telemetry.sh
ssh YOUR_USER@<router-ip> 'echo "*/5 * * * * YOUR_DEPLOY_PATH/avery-telemetry.sh" >> /etc/crontabs/root'Per-service state machine tracking across the full stack. Five-minute check interval. Fires on down-transitions and all recovery events. Cooldown logic prevents notification storms during extended outages while preserving first-event and all-recovery notification guarantees. Service list and cooldown interval are operator-configured.
Minute-interval container memory monitor. Evaluates utilization against a configurable threshold. Triggers docker restart with Slack notification before any hard Docker memory limit engages. Prevents the abrupt process kills that occur at hard limits, which in stateful services produce data loss rather than clean recovery. Container list and threshold are operator-configured.
Daily scheduled host scanner with JSONL output and Slack alerting on match. Bounded to high-risk filesystem locations per CISA guidance. Runs at lowest CPU and IO scheduling priority. Excludes container volumes, package stores, and high-throughput directories explicitly. Match events route through the standard alert pipeline.
No network addresses, credentials, or infrastructure identifiers appear in any file in this repository. All operational parameters are environment-variable driven.
cp config/.env.example .env| Variable | Description |
|---|---|
WAZUH_TAILSCALE_IP |
Overlay address of the detection engine |
WAZUH_SYSLOG_PORT |
UDP syslog ingestion port |
SLACK_WEBHOOK_URL |
Notification delivery endpoint |
ALERT_LEVEL_THRESHOLD |
Minimum detection severity for notification |
MAXMIND_DB_PATH |
GeoIP database path |
AGENT_TARGET_IP |
Edge agent overlay target address |
AGENT_TARGET_PORT |
Edge agent target port |
AVERY_HOSTNAME |
Platform identifier for alert context |
WAZUH_DASHBOARD_PORT |
Detection engine dashboard port |
MISP_PORT |
Threat intelligence platform port |
VELOCIRAPTOR_PORT |
DFIR platform port |
SHUFFLE_PORT |
Orchestration platform port |
OPENCTI_PORT |
CTI platform port |
ARKIME_PORT |
Packet capture platform port |
Why AlmaLinux 9
The tooling ecosystem relevant to this deployment has deep, well-maintained support for RHEL-compatible distributions. More practically: production stability is a non-negotiable requirement for a detection platform. A platform that requires maintenance or goes offline during an active operation provides negative operational value, the absence of detection is indistinguishable from successful evasion. AlmaLinux's long-term support commitment and binary compatibility with the RHEL ecosystem satisfy both the ecosystem requirement and the stability requirement without compromise.
Why a zero-trust overlay for all inter-service communication
The conventional alternative is binding services to specific host network interfaces and enforcing inter-service isolation through access control lists. This approach has two failure modes that are relevant here. First, ACL accuracy degrades under operational pressure — rules accumulate, exceptions are added, and the actual enforcement posture drifts from the intended posture in ways that are not always immediately visible. Second, any misconfiguration that exposes a service port to an unintended network segment creates an attack surface that did not exist in the original design.
The overlay approach eliminates both failure modes. Services have no host-network listener, the interface does not exist. Inter-service communication paths are defined by overlay mesh provisioning, which is version-controlled and auditable. The security property does not depend on ACL accuracy because there is no ACL to become inaccurate. Misconfiguration cannot create an unintended exposure path because the exposure path requires explicit provisioning to exist at all.
Why surgical config injection over file rewrites
Production configuration files on a running detection platform are not static artifacts. They accumulate operational state over time — detection tuning decisions made in response to specific incident patterns, threshold adjustments validated against observed traffic, local modifications that reflect characteristics of the specific environment. None of this state is represented in deployment scripts. Automation that overwrites configuration files on each run silently destroys it, and the system will not surface the loss until the next time that tuning decision matters.
All automation in this repository injects changes through marker-based surgical edits. The existing file state is preserved. The exact scope of each automated change is visible in version control. Re-running the automation produces no side effects if the change has already been applied. This is a more conservative approach than file-overwrite automation, and the conservatism is appropriate for a production detection system where unexpected configuration changes have direct operational consequences.
Why a custom alert notification integration
The default notification format produced by most security tools was designed to be parseable, not actionable. A wall of flat text that contains the right information does not serve an analyst who is working under time pressure across a high-volume alert queue. Every second spent mentally parsing notification format is a second not spent on the triage decision.
The custom integration formats every notification as a structured Block Kit message with visual severity encoding, immediately readable MITRE ATT&CK context, and a layout optimized for fast human consumption. The design goal is to reduce the time between notification receipt and triage decision to the minimum that the available information supports. Under sustained alert pressure, that reduction has measurable operational impact.
The detection infrastructure in this repository is the substrate for a research program whose questions are not documented here.
The work requires production-fidelity telemetry at operational scale. Synthetic environments and simulated adversary behavior are insufficient for the class of problems being investigated — the signals of interest only appear under real operational conditions, and the models being developed require real data to build and validate. The current deployment provides that substrate.
The research direction, framing, and open problems are in docs/VISION.md. It is written for practitioners. Reading the current repository before reading VISION.md is the intended order.
AVERY is not a community project and is not accepting general contributions.
Collaboration is considered where a researcher or practitioner is actively working on problems that intersect directly with the research direction in docs/VISION.md and has something specific to bring to that intersection. If that describes your situation, open an issue and describe the problem you are working on. The conversation starts from there.
MIT License