Skip to content

Contributing

HYDRA × PDX is an open-source research project. Contributions are welcome.

Getting started

# Fork and clone
git clone https://github.com/YOUR_USERNAME/hydra-pdx.git
cd hydra-pdx

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run tests
python -m pytest tests/

Areas where help is needed

High priority

  • New personas — Design additional high-value target simulations (e.g., healthcare server, CI/CD pipeline, Kubernetes node). Each persona needs a fs_blueprint.yaml, LLM context, hostname, services, and decoy credentials.
  • PromptGuard patterns — Expand the regex pattern library with new injection techniques observed in the wild.
  • Built-in commands — Add realistic output for commands not yet in the 65+ built-in list. Priority: Docker commands, Kubernetes commands, systemd management.
  • MITRE ATT&CK coverage — Extend the pattern matching to cover more techniques beyond the current 20+ patterns.

Medium priority

  • Burp Suite extension improvements — Better delta extraction, support for WebSocket traffic, GraphQL-specific analysis.
  • Additional training generators — New fine-tuning formats (e.g., ORPO, KTO).
  • Dashboard — A web UI for monitoring HYDRA sessions in real time.
  • Multi-language support — Documentation translations beyond French.

Low priority (nice to have)

  • Alternative LLM backends — Add support for more LLM providers beyond Groq and Ollama.
  • STIX/SARIF export — Export PDX deltas in standard reporting formats.
  • Nuclei template generation — Automatically generate Nuclei detection templates from observed attack patterns.

Code structure

hydra-pdx/
├── hydra-honeypot/          # HYDRA SSH honeypot
│   ├── src/                 # Core modules
│   ├── config/              # YAML configs + SSH keys
│   ├── data/                # feedback.yaml
│   ├── logs/                # Session JSONL files
│   └── tests/
├── pdx/                     # PDX pipeline
│   ├── engines/             # Multi-model router
│   ├── training/            # Data collectors + generators
│   ├── specs/               # YAML scan specifications
│   └── tests/
└── hydra-pdx-docs/          # This documentation
    ├── docs/
    └── mkdocs.yml

Guidelines

  • Python 3.10+ — Use type hints, dataclasses, and f-strings.
  • Tests — Add tests for new features. Run pytest before submitting.
  • Commit messages — Use conventional format: feat: add Docker persona, fix: VFS mkdir race condition, docs: update builtin count.
  • No real credentials — Never commit real API keys, passwords, or tokens. All decoy credentials must be obviously fake.
  • Ethical use — This project is for security research and education. Contributions that facilitate unauthorized access or malicious activity will be rejected.

Submitting changes

  1. Create a feature branch: git checkout -b feat/docker-persona
  2. Make your changes, add tests
  3. Run python -m pytest tests/ — all tests must pass
  4. Commit with a descriptive message
  5. Push and open a Pull Request against main
  6. Describe what you changed and why in the PR description

Documentation

The docs use MkDocs Material with the i18n plugin. To preview locally:

cd hydra-pdx-docs
pip install -r requirements.txt
mkdocs serve

For French translations, create a file with the .fr.md suffix alongside the English version. For example, docs/hydra/overview.md → docs/hydra/overview.fr.md.

Questions?

Open a GitHub Discussion or reach out on LinkedIn.