chore: enforce strict typing and internal naming conventions across web components
This commit is contained in:
103
GEMINI.md
Normal file
103
GEMINI.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# DECNET (Deception Network) Project Context
|
||||
|
||||
DECNET is a high-fidelity honeypot framework designed to deploy heterogeneous fleets of fake machines (called **deckies**) that appear as real hosts on a local network.
|
||||
|
||||
## Project Overview
|
||||
|
||||
- **Core Purpose:** To lure, profile, and log attacker interactions within a controlled, deceptive environment.
|
||||
- **Key Technology:** Linux-native container networking (MACVLAN/IPvlan) combined with Docker to give each decoy its own MAC address, IP, and realistic TCP/IP stack behavior.
|
||||
- **Main Components:**
|
||||
- **Deckies:** Group of containers sharing a network namespace (one base container + multiple service containers).
|
||||
- **Archetypes:** Pre-defined machine profiles (e.g., `windows-workstation`, `linux-server`) that bundle services and OS fingerprints.
|
||||
- **Services:** Modular honeypot plugins (SSH, SMB, RDP, etc.) built as `BaseService` subclasses.
|
||||
- **OS Fingerprinting:** Sysctl-based TCP/IP stack tuning to spoof OS detection (nmap).
|
||||
- **Logging Pipeline:** RFC 5424 syslog forwarding to an isolated SIEM/ELK stack.
|
||||
|
||||
## Technical Stack
|
||||
|
||||
- **Language:** Python 3.11+
|
||||
- **CLI Framework:** [Typer](https://typer.tiangolo.com/)
|
||||
- **Data Validation:** [Pydantic v2](https://docs.pydantic.dev/)
|
||||
- **Orchestration:** Docker Engine 24+ (via Docker SDK for Python)
|
||||
- **Networking:** MACVLAN (default) or IPvlan L2 (for WiFi/restricted environments).
|
||||
- **Testing:** Pytest (100% pass requirement).
|
||||
- **Formatting/Linting:** Ruff, Bandit (SAST), pip-audit.
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
Host NIC (eth0)
|
||||
└── MACVLAN Bridge
|
||||
├── Decky-01 (192.168.1.10) -> [Base] + [SSH] + [HTTP]
|
||||
├── Decky-02 (192.168.1.11) -> [Base] + [SMB] + [RDP]
|
||||
└── ...
|
||||
```
|
||||
|
||||
- **Base Container:** Owns the IP/MAC, sets `sysctls` for OS spoofing, and runs `sleep infinity`.
|
||||
- **Service Containers:** Use `network_mode: service:<base>` to share the identity and networking of the base container.
|
||||
- **Isolation:** Decoy traffic is strictly separated from the logging network.
|
||||
|
||||
## Key Commands
|
||||
|
||||
### Development & Maintenance
|
||||
- **Install (Dev):**
|
||||
- `rm .venv -rf`
|
||||
- `python3 -m venv .venv`
|
||||
- `source .venv/bin/activate`
|
||||
- `pip install -e .`
|
||||
- **Run Tests:** `pytest` (Run before any commit)
|
||||
- **Linting:** `ruff check .`
|
||||
- **Security Scan:** `bandit -r decnet/`
|
||||
- **Web Git:** git.resacachile.cl (Gitea)
|
||||
|
||||
### CLI Usage
|
||||
- **List Services:** `decnet services`
|
||||
- **List Archetypes:** `decnet archetypes`
|
||||
- **Dry Run (Compose Gen):** `decnet deploy --deckies 3 --randomize-services --dry-run`
|
||||
- **Deploy (Full):** `sudo .venv/bin/decnet deploy --interface eth0 --deckies 5 --randomize-services`
|
||||
- **Status:** `decnet status`
|
||||
- **Teardown:** `sudo .venv/bin/decnet teardown --all`
|
||||
|
||||
## Development Conventions
|
||||
|
||||
- **Code Style:**
|
||||
- Strict adherence to Ruff/PEP8.
|
||||
- **Always use typed variables**. If any non-types variables are found, they must be corrected.
|
||||
- The correct way is `x: int = 1`, never `x : int = 1`.
|
||||
- If assignment is present, always use a space between the type and the equal sign `x: int = 1`.
|
||||
- **Never** use lowercase L (l), uppercase o (O) or uppercase i (i) in single-character names.
|
||||
- **Internal vars are to be declared with an underscore** (_internal_variable_name).
|
||||
- **Internal to internal vars are to be declared with double underscore** (__internal_variable_name).
|
||||
- Always use snake_case for code.
|
||||
- Always use PascalCase for classes and generics.
|
||||
- **Testing:** New features MUST include a `pytest` case. 100% test pass rate is mandatory before merging.
|
||||
- **Plugin System:**
|
||||
- New services go in `decnet/services/<name>.py`.
|
||||
- Subclass `decnet.services.base.BaseService`.
|
||||
- The registry uses auto-discovery; no manual registration required.
|
||||
- **Configuration:**
|
||||
- Use Pydantic models in `decnet/config.py` for any new settings.
|
||||
- INI file parsing is handled in `decnet/ini_loader.py`.
|
||||
- **State Management:**
|
||||
- Runtime state is persisted in `decnet-state.json`.
|
||||
- Do not modify this file manually.
|
||||
- **General Development Guidelines**:
|
||||
- **Never** commit broken code.
|
||||
- **No matter how small** the changes, they must be committed.
|
||||
- **If new features are addedd** new tests must be added, too.
|
||||
- **Never present broken code to the user**. Test, validate, then present.
|
||||
- **Extensive testing** for every function must be created.
|
||||
- **Always develop in the `dev` branch, never in `main`.**
|
||||
- **Test in the `testing` branch.**
|
||||
|
||||
## Directory Structure
|
||||
|
||||
- `decnet/`: Main source code.
|
||||
- `services/`: Honeypot service implementations.
|
||||
- `logging/`: Syslog formatting and forwarding logic.
|
||||
- `correlation/`: (In Progress) Logic for grouping attacker events.
|
||||
- `templates/`: Dockerfiles and entrypoint scripts for services.
|
||||
- `tests/`: Pytest suite.
|
||||
- `pyproject.toml`: Dependency and entry point definitions.
|
||||
- `CLAUDE.md`: Claude-specific environment guidance.
|
||||
- `DEVELOPMENT.md`: Roadmap and TODOs.
|
||||
Reference in New Issue
Block a user