Home - sparkycz1/honeypot-shelf GitHub Wiki

A fleet of decoys, watched from one browser tab — every fake login attempt lands here first.

Management and monitoring for a fleet of OpenCanary honeypots (Raspberry Pis, Debian, or Ubuntu boxes at customer sites — see Initialize for the six supported OS releases), scoped per company — every page needs a login (local, LDAP, or OIDC, plus TOTP/passkey 2FA), and what an account can see is gated by RBAC (see Authentication & RBAC). A honeypot is managed exactly like a machine in debcontrol (a sister project for Debian fleets, where this project's stack, layout, auth system, and SSH management layer were all ported from) — plus this project's own addition: an SSH poll reads OpenCanary's own events straight off each honeypot, and the Dashboard sums them per company. Full "what was reused vs. what's different" story in CLAUDE.md; this page is the map, not the territory.

flowchart LR
    App(("🐝 Honeypot Shelf"))
    App --> Dash["📊 Dashboard"]
    App --> H["🍯 Honeypots"]
    App --> Map["🗺️ Map"]
    App --> Notif["🔔 Notifications"]
    App --> Init["🌱 Initialize"]
    App --> Sched["⏱️ Scheduling"]
    App --> Comp["🏢 Companies"]
    App --> Set["⚙️ Settings"]
    H --> H1["Overview · Monitoring · Activity<br/>Updates · Terminal · Logs · Config"]

    classDef hub fill:#1b2430,stroke:#f2a83a,stroke-width:2px,color:#fff
    classDef leaf fill:#f2a83a,stroke:#1b2430,stroke-width:1px,color:#1b2430
    classDef sub fill:#f4f4f4,stroke:#1b2430,color:#1b2430
    class App hub
    class Dash,H,Map,Notif,Init,Sched,Comp,Set leaf
    class H1 sub

Honeypot Shelf only ever speaks plain HTTP (port 8080) — it expects a TLS terminator in front of it, always. Pick your fighter:

• Caddy — bundled, zero-config HTTPS. The easy button.
• nginx — you already run one for everything else.
• Traefik — you're already all-in on Docker labels.

Want the granular, paragraph-by-paragraph feature list this page used to carry? That level of detail lives where it belongs — next to the why, split across Architecture and its Authentication & RBAC, Honeypot Management, Audit Log, and Notifications companion pages — so this page stays something you can actually read in one sitting.

• Who can create a company/honeypot/user? Superadmin only. A company user (READ/READ_WRITE) never creates a company or another user — a READ_WRITE user does manage the honeypots already in their own company (create/edit/delete, terminal, updates, power). Companies, Users, Settings, and the Audit log stay superadmin-only end to end. In the header they sit together under one Administration menu, with API docs for an account that has API access; the everyday pages (Dashboard, Honeypots, Map, Notifications, Initialize, Scheduling) stay in the bar.
• Notifications: self-service, named rules in the nav bar — any user, regardless of access level, creates their own named alert rules, each scoped to a whole company (every honeypot in it, superadmin sees every company) or a single honeypot, by email, webhook, push app or team chat, with independent alert/unavailable/recovered toggles and their own debounce thresholds — plus a "Send test" button and their own notification history. Deliberately much simpler than a role/condition-based rules engine — see Notifications. The three syslog targets (global audit-only, per-company alerts, fleet-wide alerts — see Honeypot Management) remain the "forward to your own SIEM" path, unrelated to this.
• Retention defaults: events, audit log entries, and dashboard trend snapshots all default to 90 days — still adjustable from Settings.
• Impersonate: a superadmin can sign in as any other (non-superadmin) account for support/debugging, from the Users list — see Authentication & RBAC for the safeguards and audit trail.
• GeoIP / Map: an alert's (or a login's) source IP is resolved to a country/city/lat-long once, at write time, from a MaxMind-DB-format database the app downloads itself (never bundled — see Settings → GeoIP) — only ever for a public IP, never a private/internal one. The Map page plots it on a real, pannable/zoomable world coastline (traced from Natural Earth's public-domain land outline, no country borders/labels) plus a top-countries table, company-scoped like the Dashboard; the audit log shows the same resolved country next to each entry's IP. See Honeypot Management.