admin/andreicscs-HoneyWire
1
0
Fork 0
mirror of https://github.com/andreicscs/HoneyWire synced 2026-06-26 12:39:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

updated docs to reflect current changes made so far

Browse Source
This commit is contained in:
AndReicscs
2026-06-21 13:28:06 +00:00
parent 5debf7f5d3
commit dd7715fbed
8 changed files with 121 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+39 -47
View File
@@ -8,67 +8,59 @@ Whether you want to build a new decoy sensor, improve the Vue.js frontend, or op
---
## Project Structure
## Development Documentation
To help you navigate the repository, here is a high-level overview of the architecture:
To keep this guide concise, we have moved the in-depth technical guides to the **[Development Docs](./Docs/development/README.md)** directory.
```text
honeywire/
├── .github/ # CI/CD workflows
├── Docs/ # Documentation (API.md)
├── Hub/ # Central brain (Go backend + Vue frontend)
│ ├── cmd/hub/ # Main Go entrypoint (main.go)
│ ├── internal/ # Go packages (api, auth, config, models, notify, store)
│ ├── ui/ # Vue 3 Frontend (src, public, tailwind config)
│ ├── docker-compose.yml
│ └── Dockerfile
├── SDKs/ # Libraries for writing custom sensors
└── Sensors/ # Decoy nodes (Official and Community)
```
Before contributing, please review the relevant documentation:
- **[Local Setup & Environment](./Docs/development/setup.md)**: How to spin up the Hub, Frontend, and Mock Hub.
- **[Contribution Rules](./Docs/development/contributionRules.md)**: Essential coding standards, branching strategies, and PR guidelines.
- **[Building Sensors](./Docs/development/sensors.md)**: A complete guide to creating, testing, and submitting new deception sensors.
- **[Wizard Development](./Docs/development/wizard.md)**: Guidelines for contributing to the Wizard CLI engine.
- **[Maintainer Workflow](./Docs/development/maintainer-workflow.md)**: Internal workflows for tagging, releasing, and updating the manifest registry.
---
## Contributing to the Hub (Core)
## Project Structure
The Hub is a unified monolith containing both the Go API and the embedded Vue 3 frontend.
Here is a high-level overview of the HoneyWire repository:
### Frontend (Vue 3 + TailwindCSS)
1. Navigate to the `Hub/ui/` directory.
2. Run `npm install` to install dependencies.
3. Run `npm run dev` to start the Vite development server.
* *Note: You will need the Go backend running concurrently to serve the `/api/v1` routes.*
4. When your UI changes are complete, run `npm run build`. This compiles the assets into `Hub/ui/dist/`, which the Go binary automatically embeds at compile time.
### Backend (Go 1.25 + SQLite)
1. Navigate to the `Hub/` directory.
2. The backend uses `modernc.org/sqlite` (a pure Go port of SQLite) to ensure the binary remains statically linked and cross-platform without requiring CGO.
3. Run `go run cmd/hub/main.go` to start the Hub.
4. **Database Migrations:** If you need to alter the database schema, **do not** modify the `baselineSchema` string in `Hub/internal/store/store.go`. Instead, append your `ALTER TABLE` SQL command to the `migrations` array within that file. The Hub will safely backup the database and apply the migration automatically on boot.
```text
honeywire/
├── Docs/ # Comprehensive documentation (Architecture, Development, Security)
├── Hub/ # Central brain (Go backend + Vue 3 frontend)
│ ├── cmd/hub/ # Main Go entrypoint
│ ├── internal/ # Go packages (api, store, registry)
│ └── ui/ # Vue 3 Frontend (Vite + TailwindCSS)
├── SDKs/ # Language SDKs (Go, Python) for building sensors
├── Sensors/ # Decoy nodes
│ ├── official/ # First-party maintained sensors
│ ├── community/ # Community-submitted sensors
│ └── templates/ # Boilerplate templates (go-sensor, python-sensor)
├── wizard/ # The Wizard CLI (Intelligent Deception Deployment)
└── scripts/ # Utility scripts (e.g., mock_hub.py for testing)
```
---
## Contributing a New Sensor
To keep the ecosystem stable, all community-submitted sensors must adhere to a strict set of DevSecOps rules. We treat sensors as **isolated, unprivileged microservices**.
To keep the ecosystem stable, all community-submitted sensors must adhere to our DevSecOps rules. We treat sensors as **isolated, unprivileged microservices**.
### The Golden Rules of Sensors
1. **Strict Sandboxing (Docker Only):** Every sensor must include a `Dockerfile`. We strongly enforce the use of minimal, hardened base images (like Distroless) running as non-root users (`UID 65532`) with all Linux kernel capabilities dropped (`cap_drop: ALL`).
2. **Zero Blast Radius:** Your sensor must not crash or overwhelm the main Hub. All communication must happen asynchronously via HTTP POST requests containing JSON.
3. **No Hardcoding:** All configurations (Ports, Node keys, file paths, thresholds) must be handled dynamically via environment variables.
1. **Use the Official Templates:** Start by copying either the `go-sensor` or `python-sensor` folder from [`Sensors/templates/`](./Sensors/templates/) into [`Sensors/community/`](./Sensors/community/).
2. **Follow the Data Contract:** Your sensor must POST a payload matching the Universal Event Standard. Using the provided SDKs handles this for you.
3. **Strict Sandboxing:** We strongly enforce the use of minimal, hardened base images (like Distroless) running as non-root users (`UID 65532`) with all Linux kernel capabilities dropped (`cap_drop: ALL`).
4. **Implement Test Mode:** Our CI pipeline tests your sensor by passing `HW_TEST_MODE=true`. Ensure your code handles this by securely sending a heartbeat and mock event before exiting gracefully.
### How to Submit
1. **Use the Official Template:** Copy the [`Sensors/templates/go-sensor-template/`](./Sensors/templates/go-sensor-template/) folder and rename it to your sensor's name inside the [`Sensors/community/`](./Sensors/community/) directory.
*While you can technically build a custom sensor in any language, **pure Go is the official standard** for HoneyWire due to its minimal footprint, concurrency models, and ability to compile statically.*
2. **Follow the JSON Contract:** Your sensor must POST a payload to the Hub matching the schema outlined in the main `README.md`. *(The official HoneyWire Go SDK handles this formatting for you).*
3. **Implement Test Mode:** To ensure your code works before merging, our GitHub Actions will pass `HW_TEST_MODE=true` to your container. Your sensor must immediately send a synthetic payload to the Hub and exit gracefully.
4. **Documentation:** Provide a `README.md` within your sensor directory containing:
* **Technical Overview:** Purpose of the sensor.
* **Environment Reference:** A table of all `HW_` configuration variables.
* **Deployment Example:** A secure `docker-compose.yml` snippet.
* **Security Architecture:** An explicit breakdown of the capability drops and isolation techniques utilized.
For step-by-step instructions, please read the **[Sensor Development Guide](./Docs/development/sensors.md)**.
---
## Review Process
### Review Process
Once you open a Pull Request:
1. **Automated Security Scanning:** GitHub Actions will run **Trivy** to scan your Docker image for vulnerabilities, and **CodeQL** to perform static code analysis for memory leaks.
2. **Functional Testing:** GitHub Actions will automatically build your Docker container and test it against a Mock Hub using `HW_TEST_MODE=true`.
1. **Automated Security Scanning:** GitHub Actions/Gitea will run **Trivy** to scan your Docker image for vulnerabilities, and **CodeQL** to perform static code analysis.
2. **Functional Testing:** Our CI will automatically build your Docker container and test it against a Mock Hub.
3. **Manual Review:** A core maintainer will manually review the code, specifically checking for malicious intent and proper capability stripping.
Join us in building a smarter, faster, and more resilient distributed defense.
Docs/development/contributionRules.md
+3 -3
View File
@@ -25,7 +25,7 @@ To maintain a stable, secure, and cohesive platform, all contributions to HoneyW
HoneyWire relies on strict JSON contracts to communicate across distributed components. Any changes to API payloads must be backward compatible.
* Before modifying telemetry shapes, review the Data Contracts.
* Before modifying telemetry shapes, review the [Data Contracts](../architecture/dataContracts.md).
* Sensors and the Hub must agree on the standard. If you introduce a new field to an event, ensure the frontend can render it without crashing if the field is missing from older events.
## 3. Testing Requirements
@@ -34,7 +34,7 @@ All submissions must pass automated CI checks.
* **Unit Tests:** New business logic in the Go backend (`internal/services/`) requires accompanying `_test.go` files.
* **Test Mode Compliance:** If you submit a new sensor, it must support `HW_TEST_MODE=true`. When this flag is passed, the container must immediately fire a synthetic alert to the Hub and exit with code 0.
* **Security Scanning:** Your PR must pass automated CodeQL (static analysis) and Trivy (container vulnerability) scans.
* **Security Scanning:** Your PR must pass automated CodeQL (or Semgrep) static analysis and Trivy container vulnerability scans.
## 4. Pull Request Expectations
@@ -50,4 +50,4 @@ All submissions must pass automated CI checks.
If you discover a vulnerability in HoneyWire, **do not open a public issue or PR.**
Please use GitHub Private Vulnerability Reporting via the Security tab on the repository, as outlined in `SECURITY.md`.
Please use GitHub Private Vulnerability Reporting via the Security tab on the repository, as outlined in [SECURITY.md](../../SECURITY.md).
Docs/development/sensors.md
+6 -6
View File
@@ -17,8 +17,8 @@ While you can technically write a sensor in any language using HTTP POST request
### Basic Implementation
Instead of starting from scratch, always use the official Go Sensor Template located at `Sensors/templates/go-sensor/`.
This directory contains a pre-configured `main.go` file with detailed comments, a hardened `Dockerfile`, and a `docker-compose.yml` file that orchestrates the required security capabilities out-of-the-box.
Instead of starting from scratch, always use the official templates located at [`Sensors/templates/`](../../Sensors/templates/).
See the [Templates README](../../Sensors/templates/README.md) and the [Community Sensors README](../../Sensors/community/README.md) for more details. These directories contain pre-configured `main.go` and `sensor.py` files with detailed comments, hardened `Dockerfile`s, and `docker-compose.yml` files that orchestrate the required security capabilities out-of-the-box.
---
@@ -26,14 +26,14 @@ This directory contains a pre-configured `main.go` file with detailed comments,
The manifest is the single source of truth for your sensor. It defines how the Hub renders its UI card, how the Wizard deploys it, and what heuristics trigger a recommendation.
Instead of starting from scratch, base your manifest on the template provided at `Sensors/templates/go-sensor/manifest.json`.
Instead of starting from scratch, base your manifest on the templates provided at [`Sensors/templates/go-sensor/manifest.json`](../../Sensors/templates/go-sensor/manifest.json) or [`Sensors/templates/python-sensor/manifest.json`](../../Sensors/templates/python-sensor/manifest.json).
### Key Sections
* **`heuristics`:** Instructs the Wizard when to recommend this sensor. For example, if you build an Nginx honeypot, you would set `"processes": ["nginx"]` and `"ports": [80, 443]`.
* **`deployment.env_vars`:** Defines configurable parameters that the Hub UI will generate forms for. If your sensor needs a custom configurable port, define it here.
* **`deployment.image`:** The Docker image to pull.
*(See `Docs/architecture/dataContracts.md` for the full manifest schema and required fields).*
*(See [`Docs/architecture/dataContracts.md`](../architecture/dataContracts.md) for the full manifest schema and required fields).*
---
@@ -41,7 +41,7 @@ Instead of starting from scratch, base your manifest on the template provided at
HoneyWire treats sensors as untrusted, potentially hostile execution units. **If a sensor is compromised, the blast radius must be minimal.**
To ensure compliance, **always use the `Dockerfile` and `docker-compose.yml` or manifest deployment configuration provided in `Sensors/templates/go-sensor/`**. It is pre-configured to enforce the following baseline rules:
To ensure compliance, **always use the `Dockerfile` and `docker-compose.yml` or manifest deployment configuration provided in the templates (e.g., [`Sensors/templates/go-sensor/`](../../Sensors/templates/go-sensor/))**. It is pre-configured to enforce the following baseline rules:
1. **Distroless Base:** The Dockerfile must use a minimal base image like `gcr.io/distroless/static-debian12`. No shells (`/bin/sh`), no package managers, no utilities.
2. **Prefer unprivileged Execution:** It is better for the to container run as a non-root user (e.g., `USER 65532:65532`).
@@ -78,5 +78,5 @@ HoneyWire distinguishes between two distinct ways of testing a sensor payload. B
When a sensor container boots with this flag, it acts as a short-lived execution check. It synchronously sends a test payload directly to the Hub wire (bypassing internal queues) and immediately shuts down with exit code `0`. This guarantees payload delivery before the container exits. It is strictly used for automated CI pipelines.
2. **Live In-Flight Testing (`SIGUSR1`):**
When a sensor is actively running in production, it can be tested on-demand via the Wizard CLI (`wizard test <sensor-id>`). The Wizard sends a `SIGUSR1` Unix signal to the target Docker container.
When a sensor is actively running in production, it can be tested on-demand via the Wizard CLI (`wizard firedrill`). The Wizard sends a `SIGUSR1` Unix signal to the target Docker container.
Unlike the CI test, the signal handler routes the synthetic event into the sensor's asynchronous event queue (`ReportEvent()`). This ensures the test payload traverses the exact same real-world code paths (including exponential backoff, rate limits, and network retries) as a genuine intrusion event, all without interrupting the sensor's active uptime.
Docs/development/setup.md
+2 -2
View File
@@ -2,7 +2,7 @@
This guide covers how to set up HoneyWire for local development.
For advanced CI/CD simulation (e.g., local Gitea and private Docker registries), see `maintainer-workflow.md`.
For advanced CI/CD simulation (e.g., local Gitea and private Docker registries), see [maintainer-workflow.md](./maintainer-workflow.md).
## Prerequisites
@@ -75,4 +75,4 @@ If you are building a sensor and only want to test its telemetry output without
your-sensor-image:latest
```
If successful, the Mock Hub will print `[EVENT] OK` to the console, proving your sensor's JSON payload adheres to the required data contracts.
If successful, the Mock Hub will print `[EVENT] OK` to the console, proving your sensor's JSON payload adheres to the required [Data Contracts](../architecture/dataContracts.md).
Docs/development/wizard.md
+1 -1
View File
@@ -2,7 +2,7 @@
The Wizard is HoneyWire's ephemeral, host-side orchestration engine. This guide covers how to navigate its architecture to add new commands, modify discovery logic, or debug deployment behavior.
For a conceptual overview of how the Wizard operates, see `Docs/architecture/wizard/overview.md`.
For a conceptual overview of how the Wizard operates, see [`Docs/architecture/wizard/overview.md`](../architecture/wizard/overview.md).
---
README.md
+30 -51
View File
@@ -31,13 +31,14 @@
- [Operational Checklist](#operational-checklist)
## Overview
**HoneyWire Sentinel** is a lightweight, Distributed High-Signal Security Early-Warning System, designed for internal networks. It replaces the "magnifying glass" approach of traditional SIEMs, which often drown analysts in false positives by surveilling legitimate traffic, with a High-Fidelity Tripwire model.
**HoneyWire** is a lightweight, Distributed High-Signal Security Early-Warning System Builder, designed for internal networks. It leverages its architecture and UX to make it incredibly easy to build a new Cyber Canary server or deploy HoneyWires on existing ones. Using deception technology, it replaces the "magnifying glass" approach of traditional SIEMs which often drown analysts in false positives by surveilling legitimate traffic with a High-Fidelity Tripwire model.
Place a sensor exactly where you want it. If it trips, you have an intruder.
- **Production Tripwires**: Sound the alarm when active services are being poked in ways they shouldn't be. By placing a sensor on a sensitive file that should never be read or a service port that should never be accessed, you identify intruders by their deviation from the "authorized path."
- **Synthetic Deception**: Deploy lures like the [ICMP Canary](./Sensors/official/IcmpCanary/) or [Network Scan Detector](./Sensors/official/NetworkScanDetector/) to act as decoys. Since these sensors provide no legitimate business value, 100% of their traffic is actionable intelligence.
Set up multiple and you start to have a pretty clear idea of the lateral movement of an intruder. No tuning, no noise, just instant forensics.
If you have legitimate automated security scanners tripping HoneyWires just whitelist them from the Hub's settings.
## Showcase
@@ -50,38 +51,38 @@ Set up multiple and you start to have a pretty clear idea of the lateral movemen
## 🔌 The Universal Event Standard (Bring Your Own Sensor)
[**Community Sensors**](./Sensors/community/)
> Note: If you build your sensor using the official HoneyWire SDKs, this JSON formatting and delivery is handled for you automatically.
The true power of HoneyWire is that the Hub is **completely sensor-agnostic**. You are not limited to the included official sensors.
The true power of HoneyWire is that the Hub and Wizard are **completely sensor-agnostic**. You are not limited to the included official sensors.
By adhering to the **HoneyWire Event Standard V1.0**, you can write a script in *any* language (Bash, Go, Rust, Python) to monitor *anything*, and the Sentinel UI will dynamically parse, syntax-highlight, and render your forensic data.
By adhering to the **HoneyWire Event Standard V2.0**, you can write a script in *any* language (Bash, Go, Rust, Python) to monitor *anything*, and the Sentinel UI will dynamically parse, syntax-highlight, and render your forensic data.
Whether it is a **Deep Packet Inspection (DPI)** engine, a **DNS sinkhole**, a **Canary Token** embedded in a PDF, an **Email Honeypot**, or a simple **TCP Port Tripwire**, just POST the **Universal Event Standard** JSON payload to the Hub.
> 📖 **[View the full Event Data Contract here](./Docs/architecture/dataContracts.md#1-the-universal-event-standard)**
> Note: If you build your sensor using the official HoneyWire SDKs, this JSON formatting and delivery is handled for you automatically.
*The Hub's frontend automatically translates arrays into syntax-highlighted code blocks and primitive values into clean detail tags.*
> **[View the full Event Data Contract here](./Docs/architecture/dataContracts.md#1-the-universal-event-standard)**
## Features
- **The Sentinel Hub UI:** A fully responsive, Vue 3-powered dashboard featuring Dark/Light mode, live WebSocket event streaming, and dynamic forensic payload inspection.
- **In-Browser Configuration:** Manage Master Passwords, Node Keys, Data Retention policies, and Webhooks directly from the UI. No need to touch `.env` files or restart containers to update alert targets.
- **The Sentinel Hub UI:** A fully responsive, Vue 3-powered dashboard featuring dynamic forensic payload inspection, Nodes and Sensors deployment and management, including sensor updates, directly from the UI.
- **Universal Push Notifications:** Native, zero-dependency integration for routing critical alerts to **Discord, Slack, Ntfy, and Gotify**.
- **Enterprise SIEM Integration:** Native RFC 3164 Syslog forwarding (TCP/UDP) for seamlessly pushing structured telemetry to Splunk, Elastic, Wazuh, or Vector.
- **Suite of Official Sensors:** Includes native [TCP Tarpit](./Sensors/official/TcpTarpit/), [Web Router Decoy](./Sensors/official/WebRouterDecoy/), [File Canary (FIM)](./Sensors/official/FileCanary/), [ICMP Canary](./Sensors/official/IcmpCanary/), and [Network Scan Detector](./Sensors/official/NetworkScanDetector/).
- **Enterprise SIEM Integration:** Native RFC5424 Syslog forwarding (TCP/UDP) for seamlessly pushing structured telemetry to Splunk, Elastic, Wazuh, or Vector.
- **The Setup Wizard:** A deployment and testing automation tool, developed explicitly to not be a 24/7 running agent. It is simply a TUI CLI tool that automates operator tasks like applying and reconciling the Hub's desired state for a given Node, automatically handling configuration, deployment, and rollbacks on failed deployments.
- **Suite of Official HoneyWires:** Includes native [TCP Tarpit](./Sensors/official/TcpTarpit/), [Web Router Decoy](./Sensors/official/WebRouterDecoy/), [File Canary (FIM)](./Sensors/official/FileCanary/), [ICMP Canary](./Sensors/official/IcmpCanary/), and [Network Scan Detector](./Sensors/official/NetworkScanDetector/).
## Architecture
HoneyWire is split into three independent microservices:
HoneyWire is split into four independent microservices:
1. `/Hub`: The central brain. A pure Go binary running an embedded SQLite database and the Vue.js dashboard. It runs as a non-root user inside a Distroless container, safely mounting data to a dedicated volume.
2. `/Sensors`: The decoy nodes. Statically-linked Go binaries that listen on vulnerable ports, trap attackers, and securely POST intrusion data back to the Hub.
3. `/SDKs`: Official libraries (like `sdk-go`) that handle secure Hub communication so community developers can easily build new sensors.
4. `/wizard`: Setup wizard cli tool to automate operator tasks such as discovery, deployment and testing of HoneyWires.
> **[Check out the full architecture docs](./Docs/architecture/README.md)**
## 🚀 Quick Start Guide
Deploying the HoneyWire Hub takes less than 60 seconds using our pre-built GitHub Container images. No compiling is required.
Deploying the HoneyWire Hub takes less than 60 seconds using our pre-built GitHub Container images.
### 1. Deploy the Hub
Create a new directory on your server, create a `docker-compose.yml` file, and paste the following:
@@ -91,17 +92,17 @@ services:
# 1. THE PERMISSION FIXER: Runs once to ensure the Hub can write to the data volume
permission-fixer:
image: alpine:latest
container_name: honeywire-permission-fixer
command: sh -c "chown -R 65532:65532 /data"
volumes:
- ./honeywire_data:/data
# 2. THE HUB: The central Go-based dashboard and API
hub:
image: ghcr.io/andreicscs/honeywire-hub:latest
image: registry.honeywire.dev/honeywire-hub:latest
container_name: honeywire-hub
restart: unless-stopped
ports:
# Change 8080 to whatever port you prefer
- "8080:8080"
volumes:
- ./honeywire_data:/data
@@ -118,6 +119,7 @@ services:
environment:
- HW_ENV=development # Required if not using HTTPS, or the cookie will have the secure flag set, in production it is highly recommended to remove this and run this behind a reverse proxy using https
- HW_PORT=8080
- HW_DB_PATH=/data/honeywire.db
# Optional: Hardcode the dashboard password (disables the UI password reset feature)
# - HW_DASHBOARD_PASSWORD=admin
```
@@ -128,49 +130,35 @@ docker compose up -d
```
### 2. Initialize the System
Navigate to `http://<your-server-ip>:8080` in your browser. You will be greeted by the **Initialize Sentinel** screen.
Navigate to `http://<your-server-ip>:HW_PORT` in your browser. You will be greeted by the **Initialize Sentinel** screen.
1. Create your Master Password.
2. Verify your Hub Endpoint URL (the IP/URL where sensors will reach the Hub).
3. Provision a Node and generate its secure Node Key.
4. Click "Initialize Hub".
3. Click "Initialize Hub".
### 3. Deploy Sensors
Inside the Dashboard, navigate to the **Sensor Store**. Click on any sensor (e.g., the TCP Tarpit) to view its documentation. The Hub will automatically generate a ready-to-use `docker-compose.yml` script pre-filled with your Hub\'s IP and Node Key. Copy that script, drop it on your target machine, and run `docker compose up -d`!
1. Create a new Node and paste the provided command to install and link the Setup Wizard to the hub
2. Install sensors directly from the Hub and then run `honeywire apply` on the node to reconcile desired state or run `honeywire discover` to let the Setup wizard automatically scan and suggest HoneyWires based on environment.
### 4. Testing the HoneyWires
### 4. Testing the Trap
Once your containers are up, the Tarpit sensor should appear as `ONLINE` in the **Fleet Health** section of the dashboard within 30 seconds.
If you deployed the TcpTarpit sensor, to verify the detection loop, use `netcat` from a different machine (or a different terminal) to trigger the decoy:
```bash
# Connect to your decoy port (e.g., 2222) at localhost (or your server's IP).
nc localhost 2222
```
1. **Observe the Lure:** If `HW_TARPIT_MODE` is set to `hold` or `echo`, you will see your fake service banner immediately.
2. **Interact:** The connection will be intentionally stalled (Tarpit). Type a string (e.g., `admin` or `exploit_payload`) and press Enter.
3. **Close:** Press `Ctrl+C` to terminate the test connection.
4. **Verify Capture:**
- Check the HoneyWire Dashboard; the event, your Source IP, and the payload will appear instantly.
- If configured, you will receive a push notification on your mobile device.
Once your containers are up, the Tarpit sensor should appear as `ONLINE` within 30 seconds.
Run `honeywire firedrill` to make the HoneyWires send a mock event to the hub to test connectivity.
---
## Security Notes
* **Threat Model:** For a deep dive into trust boundaries, architecture risks, and sandboxing rules, see the **[THREATMODEL.md](./THREATMODEL.md)**.
* **Node Keys:** Ensure your sensors use their unique `Node Key` to communicate with the Hub. The Hub will reject any payloads with mismatched or invalid keys.
* **System Arming:** You can toggle the "System Armed" button in the Hub UI to temporarily disable push notifications while doing internal network maintenance or vulnerability scanning.
* **Container Hardening:** HoneyWire utilizes `gcr.io/distroless/static-debian12:nonroot`. We follow the principle of least privilege to make sure that if a container is compromised, the blast is contained.
* **Distributed Deployment:** It is highly recommended to run the Hub and its Sensors on separate physical or virtual machines. If an attacker compromises a sensor node, they should not have immediate local access to the centralized Hub.
* ⚠️ **Encryption (HTTPS):** Always serve the Hub Web GUI and API over HTTPS using a reverse proxy (like Nginx, Caddy, or Traefik) in production. Failure to do so exposes your Dashboard password and Node Keys to network sniffing.
* ⚠️ **Encryption (HTTPS):** Always serve the Hub Web UI and API over HTTPS using a reverse proxy (like Nginx, Caddy, or Traefik) in production. Failure to do so exposes your Dashboard password and Node Keys to network sniffing.
## Tech Stack
* **Backend:** Go 1.25, `net/http` (Standard Library), SQLite (ModernC Pure Go Driver)
* **Frontend:** Vue 3 (Composition API), TailwindCSS, Chart.js
* **Infrastructure:** Docker, Docker Compose, Distroless Linux Sandbox
* **Infrastructure:** Docker, Docker Compose v5.0.0+
## Versioning and API Reference
@@ -178,14 +166,5 @@ nc localhost 2222
- HoneyWire uses a single source of truth version file: `VERSION` in the repo root.
- The runtime version is exposed via an env override: `HW_VERSION` (Hub + Sensors), which defaults to `VERSION`.
- `Hub` endpoint:
- `GET /api/v1/version` → returns `{ "version": "1.0.0" }`
- API docs file: [📖 API.md](./Docs/API.md) with full backend route reference and sample payloads.
## Operational Checklist
- [x] Complete the Web UI Initial Setup to set the Master Password.
- [x] Provision a Node and retrieve the generated `Node Key` to apply it to your sensors.
- [x] Configure your push notification webhooks via the Settings UI.
- [x] Rebuild/redeploy containers after any version bump in `VERSION` or e
- `GET /api/v1/version` → returns `{ "version": "2.0.0" }`
- API docs file: [API.md](./Docs/architecture/hub/backend/API.md) with full backend route reference and sample payloads.
Sensors/community/README.md
+25 -74
View File
@@ -1,89 +1,40 @@
[![License](https://img.shields.io/badge/license-AGPLv3-blue.svg)](../../LICENSE)
# Community Sensor Lab
Welcome to the **HoneyWire Community Sensor Lab**. While our official sensors provide the core foundation, this directory is where the decentralized deception ecosystem truly thrives.
Welcome to the HoneyWire Community Sensor Lab. This directory provides a space to deploy, share, and experiment with custom deception sensors.
The power of HoneyWire lies in the **Universal Event Standard**—the architectural flexibility for anyone to build a specialized trap for any niche protocol and see that telemetry normalized on a central dashboard. Whether you have engineered a DNS sinkhole, a malformed JWT detector, or a custom file-integrity monitor, this is the environment to deploy and share it.
HoneyWire's architecture allows you to build a specialized trap for any protocol and visualize its telemetry in a unified dashboard using the Universal Event Standard.
---
## Data-Driven Architecture
## 🏗️ The Single Source of Truth: JSON Manifests
HoneyWire uses a unified **Data-Driven Architecture**. To add a sensor to the HoneyWire ecosystem, you do **not** need to write Vue.js frontend code or modify the Go Wizard engine.
To add a sensor to the ecosystem, you only need to define it using a `manifest.json` file. This JSON schema is responsible for:
1. Generating interactive UI forms and configuration cards in the HoneyWire Hub.
2. Providing heuristic metadata to the Wizard CLI for host recommendations.
3. Defining the deployment parameters (containers, mounts, variables) required for execution.
You only need to define your sensor in a `SensorManifest` JSON object. This single JSON block automatically:
1. Generates the interactive UI forms and documentation cards in the HoneyWire Hub.
2. Instructs the Wizard CLI's heuristic engine on when to recommend your sensor.
3. Provides the exact deployment infrastructure (`InitContainers`, `VolumeMounts`, `EnvVars`) needed to safely run it.
Please refer to the official documentation for the complete manifest schema:
**[View the Sensor Manifest Data Contract](../../Docs/architecture/dataContracts.md)**
**Example `manifest.json` Schema:**
```json
{
"id": "hw-sensor-custom-name",
"version": "1.0.0",
"schema_version": "1.0",
"name": "My Custom Trap",
"category": "network",
"osi_layer": "Application Layer",
"icon_svg": "M12...",
"description": "Short description for the Hub UI cards.",
"documentation": {
"summary": "Longer explanation for the deep-dive view.",
"sections": [
{ "title": "Features", "type": "list", "content": ["Feature 1", "Feature 2"] }
]
},
"heuristics": {
"triggers": { "processes": ["nginx"], "ports": [80] },
"recommendation_reason": "Web server detected."
},
"deployment": {
"image": "ghcr.io/yourname/custom-trap:latest",
"network_mode": "bridge",
"user": "0:0",
"env_vars": [
{
"name": "CUSTOM_VAR",
"description": "Adjustable in the Hub UI.",
"default": "8080",
"type": "int",
"required": true,
"hidden": false
}
]
}
}
```
## Engineering Resources
---
To ensure structural consistency and security, start with the provided scaffolding:
## 🛠️ Engineering Resources
Don't start from a blank repository. We have provided the scaffolding to move your sensor from a conceptual trap to a hardened, deployed container in minutes:
* **[Sensor Template](../templates/README.md):** The recommended starting point, natively integrated with the HoneyWire Go SDK and pre-configured for Distroless execution.
* **[Contribution Guide](../../CONTRIBUTING.md):** Mandatory reading covering required capability stripping, container best practices, and the JSON Contract.
* **[🐹 Go Sensor Template](./../templates/go-sensor-template/README.md):** The high-velocity starting point, natively integrated with the HoneyWire Go SDK and pre-configured for Distroless isolation.
* **[📖 Contribution Guide](./../../CONTRIBUTING.md):** **Mandatory reading.** Contains the "Golden Rules" for capability stripping, environment parity, and the JSON Contract.
* **[🔬 Reference Implementation](./../official/TcpTarpit/README.md):** A deep dive into the architecture of our production-grade TCP Tarpit, demonstrating Go routine concurrency and semaphore limits.
**Security Standard:** We encourage community submissions to follow the official architecture: statically-linked binaries running as unprivileged users inside `:nonroot` Distroless containers, with all Linux kernel capabilities that are needed explicitly added, all capabilities are dropped by default (`cap_drop: ["ALL"]`).
> **🛡️ Security Standard:** The HoneyWire ecosystem has moved past heavy interpreters. We strongly encourage community submissions to follow our official architecture: **pure Go, statically-linked binaries running as unprivileged users inside `:nonroot` Distroless containers, with all Linux kernel capabilities dropped (`cap_drop: ["ALL"]`).**
## Contribution Policy
---
Community submissions undergo automated validation before review:
## 🛡️ The Security Policy
To protect our users, every sensor submitted here undergoes a rigorous automated gauntlet before a human maintainer even looks at the code:
1. **Static Analysis:** Scanning for security vulnerabilities and memory leaks (e.g., CodeQL).
2. **Container Security:** Image vulnerability scanning (e.g., Trivy).
3. **Functional Testing:** Automated verification against a mock network contract in `HW_TEST_MODE`.
1. **Static Analysis:** CodeQL scans your Go logic for security vulnerabilities and memory leaks.
2. **Container Security:** Trivy scans your `Dockerfile` and base images for known CVEs.
3. **Functional Testing:** Our CI/CD spins up your sensor with `HW_TEST_MODE=true` and verifies its "Heartbeat" and "Event" logic against a mock network contract.
## Submitting a Sensor
> **Note:** Community sensors expand the ecosystem's detection capabilities significantly, but always remember to review the code and container privileges before deploying them in your own production environment!
---
## 🤝 How to Contribute?
1. **Fork** the repository.
2. **Create** your sensor directory: `Sensors/community/your-sensor-name`.
3. **Implement** your logic using the [HoneyWire Go SDK](../../SDKs/go-honeywire) based on the provided template.
4. **Define** your `manifest.json` ensuring it adheres to the schema.
5. **Open a Pull Request**.
**Join us in building a smarter, faster, and more resilient distributed defense.** 🐝
1. Fork the repository.
2. Create your sensor directory under `Sensors/community/your-sensor-name`.
3. Implement your sensor logic using the [HoneyWire Go SDK](../../SDKs/go-honeywire) or equivalent language SDK.
4. Define your `manifest.json` according to the official schema.
5. Open a Pull Request for review.
Sensors/templates/README.md
+12 -5
View File
@@ -1,11 +1,17 @@
# HoneyWire Go Sensor Template
# HoneyWire Sensor Templates
Welcome to the HoneyWire ecosystem! This template provides the boilerplate to build a custom, Dockerized Go security sensor.
Welcome to the HoneyWire ecosystem! This directory provides the boilerplate to build custom, Dockerized security sensors that natively report to the HoneyWire Hub.
We provide templates for the two primary supported languages:
* **`go-sensor`**
* **`python-sensor`**
## How to Build Your Sensor
1. **Copy this folder** and rename it to your sensor's name (e.g., `ssh-watcher`).
2. **Write your logic** inside `main.go`. It comes pre-wired with the `sdk-go` event loop.
1. **Copy a template folder** (either `go-sensor` or `python-sensor`) and rename it to your sensor's name (e.g., `ssh-watcher`).
2. **Write your logic** in the main application file:
* **Go Template:** Inside `main.go`. It comes pre-wired with the `sdk-go` event loop.
* **Python Template:** Inside `sensor.py`. Add any extra Python libraries you need to `requirements.txt`.
3. **Update `manifest.json`**: Add any custom `HW_` variables your sensor needs to the `env_vars` array so the Hub can dynamically configure them.
## Deployment
@@ -13,7 +19,7 @@ Welcome to the HoneyWire ecosystem! This template provides the boilerplate to bu
In the HoneyWire architecture, sensors are driven by the Hub and Wizard via `manifest.json`.
1. Define your sensor in `manifest.json`.
2. Build and push your image to a registry.
2. Build and push your Docker image to a registry.
3. Sync the manifest to your Hub, and deploy it securely using `wizard apply`.
## Testing Your Sensor
@@ -22,6 +28,7 @@ HoneyWire provides two distinct ways to test your sensor's payload delivery safe
1. **Local Boot-Time Testing (CI/CD)**: Use the internal Mock Hub to validate your payload format without booting the full server environment.
```bash
# Note: The mock hub script itself requires Python 3 to run, regardless of your sensor's language.
python3 scripts/mock_hub.py &
docker run --rm -e HW_HUB_ENDPOINT=http://<LOCAL_IP>:8080 -e HW_HUB_KEY=test_key -e HW_SENSOR_ID=test_sensor -e HW_TEST_MODE=true your-sensor-image:latest
```