ESC

Type to search, or jump to a section

Getting StartedArchitectureHoneypot EngineDetectionObservabilityOperationsTestingReference
> PressHaven alpha
Home › Docs ›Reference › Primary Literature

Primary Literature

Concrete academic, standards and technical references, and the in-repository design documents this system is built on

Foundations Academic & standards Canonical honeypot books, the OWASP WSTG and the MITRE ATT&CK framework behind the detection model. Stack Technical docs Suricata, OpenResty / Nginx Lua, Redis scripting, Elasticsearch and Kibana — the runtime this is built on. Primary sources In-repo design The design documents in this repository that every page here is grounded in.

References are grouped by kind. External works are cited by author and title so they can be located directly; the in-repository design documents are the primary sources this documentation is grounded in, each given by its path in the source repository.

Academic & Standards

  • Lance Spitzner — Honeypots: Tracking Hackers (Addison-Wesley, 2002). The foundational treatment of honeypots, the interaction-level taxonomy and the value-of-deception argument.
  • Niels Provos & Thorsten Holz — Virtual Honeypots: From Botnet Tracking to Intrusion Detection (Addison-Wesley, 2007). Low- vs high-interaction honeypots, honeyd and virtualised deployment — the lineage this per-session-pool design sits in.
  • OWASP Web Security Testing Guide (WSTG) v4.2. The WSTG-INPV / ATHN / AUTHZ / CONF / INFO category system used to label detection stages and Suricata SIDs. owasp.org/www-project-web-security-testing-guide.
  • MITRE ATT&CK framework. Adversary tactics and techniques vocabulary for describing the attack surface the decoys present. attack.mitre.org.
  • OWASP Top 10. The injection, access-control and misconfiguration classes the generic pattern rules target. owasp.org/www-project-top-ten.
  • Rule-based vs ML detection. This system deliberately favours explainable, rule-based scoring over black-box ML; the trade-off (auditability and no training data vs novel-attack recall) is discussed in the detection overview's honest assessment.

Technical Documentation

  • Suricata documentation. Rule syntax, SID allocation and the eve.json event format parsed by suricata_rules.lua. docs.suricata.io.
  • OpenResty / Nginx Lua module. The ngx.* runtime, access_by_lua phase and shared dictionaries the reverse proxy and detection pipeline run in. openresty.org.
  • Lua 5.1 reference manual — patterns. Lua pattern matching (not PCRE) as used in pattern_rules.lua; the "magic character" escaping rules behind the hyphen-escaping fix. lua.org/manual/5.1.
  • Redis — scripting & EVAL. Atomic pool assignment via a Lua script (pool_router_rules.ASSIGN_SCRIPT) and the session/state store. redis.io scripting.
  • Elasticsearch & Kibana. The SIEM index/visualisation layer; the Kibana Saved Objects API drives build_dashboards.py / export_dashboards.py. elastic.co/guide.
  • Vector (vector.dev). The log-shipping agent in the two-host, mTLS-secured pipeline (Vector → Elasticsearch). vector.dev/docs.
  • Docker Compose. The per-session pool orchestration, static pools and the two deployment overlays (docker-compose.yml vs docker-compose.db-proxy.yml). docs.docker.com/compose.

Threat Intelligence & Honeytokens

  • AbuseIPDB API & report categories. The category IDs used for report-back (15 = Hacking, 18 = Brute-Force, 19 = Bad Web Bot, 21 = Web App Attack). docs.abuseipdb.com.
  • Thinkst Canarytokens. The honeytoken / canary-token technique this project's five seeded token types (API key, DB credentials, admin password, S3 URL, JWT secret) follow. canarytokens.org.
  • MISP — threat-intelligence sharing. Context for the roadmap's feed-integration direction beyond AbuseIPDB. misp-project.org.
  • GDPR (Regulation (EU) 2016/679). The consent and data-minimisation basis for the one-way, consent-gated device signature.

In-Repository Design Documents

These are the primary sources for everything documented on this site — every number and flag here traces back to one of them:

  • ARCHITECTURE.md — overall system architecture and the request path.
  • ids/GDPR.md — the consent-gated device-signature protocol (client token, server-side IP append, salt-and-hash).
  • patterns/README.md — the generated pattern catalogue (patterns/patterns.json) that feeds both the dashboard and these docs.
  • ids/db_proxy/README.md and ids/db_proxy/COVERAGE.md — the database-layer deception overlay and its attack-coverage scope. See Honeypot Layers.
  • ids/testing/BLIND_PENTEST_PROTOCOL.md — the blind-evaluation protocol, rubric and task list behind the Blind Pentest page.
  • ids/eshop_seed/README.md — the decoy WooCommerce content seeded into honeypot pools.
  • siem/README.md and ids/vector/certs/README.md — the SIEM pipeline and its mTLS certificate setup.
  • dashboard/README.md — the PyQt6 control dashboard and its Knowledge Base.