ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Contributing to ARES
Thank you for contributing to ARES. This guide covers everything you need to get started - from dev environment setup to submitting a pull request.
Table of Contents
- Community & Discussions
- Development Environment
- Branching Strategy
- Commit Conventions
- Research Tracks
- Writing a New Module
- Testing Requirements
- Pull Request Process
- Code Guidelines & Conventions
Community & Discussions
ARES uses GitHub Discussions for community interaction. Before opening a new issue or PR, consider whether a Discussion is more appropriate:
| Channel | Use for |
|---|---|
| Discussions → Q&A | Help with installation, configuration, module usage, troubleshooting |
| Discussions → Ideas & Proposals | Feature requests, new module ideas, architectural suggestions |
| Discussions → Bug Reports | Bug reports that need discussion before becoming issues |
| Discussions → Module Development | Module design, research tradecraft, MITRE technique coverage |
| GitHub Issues | Confirmed bugs, tracked tasks, accepted feature work |
| Pull Requests | Code contributions ready for review |
| SECURITY.md | Security vulnerabilities, never in public Discussions or Issues |
Code of Conduct
All participants must follow our Code of Conduct. In particular:
- DO NOT post real credentials, hashes, tokens, or target data in any public channel
- DO NOT disclose security vulnerabilities publicly. Use SECURITY.md
- DO redact all sensitive data from logs, screenshots, and code snippets
- DO be respectful, constructive, and technically honest
Development Environment
# 1. Fork and clone
git clone https://github.com/<your-fork>/ares && cd ares
# 2. Create virtual environment
python -m venv .venv && source .venv/bin/activate
# 3. Install in dev mode
pip install -e ".[dev,pdf]"
# 4. Install pre-commit hooks
pip install pre-commit && pre-commit install
# 5. Copy and configure .env
cp .env.example .env
# Edit .env - set ARES_SECRET_KEY, ARES_ENCRYPTION_KEY, and ARES_DEFAULT_ADMIN_PASSWORD
# Generate: openssl rand -hex 32
# 6. Verify setup
ares doctor
pytest tests/unit/ -v
Branching Strategy
ARES uses short-lived branches from main:
| Branch | Purpose |
|---|---|
main |
Protected default branch; requires PR + review |
feature/<name> |
New features and modules |
fix/<name> |
Bug fixes |
hotfix/<name> |
Critical fixes that go directly to main |
security/<name> |
Security fixes; keep private until patched |
# Start a new module
git checkout main
git pull origin main
git checkout -b feature/ad-my-new-module
# When done
git push origin feature/ad-my-new-module
# Open PR targeting main
Commit Conventions
ARES uses Conventional Commits.
Pre-commit will enforce this on git commit.
<type>: <short description>
[optional body]
[optional footer: BREAKING CHANGE / Closes #issue]
| Type | Use for |
|---|---|
feat: |
New module, new feature |
fix: |
Bug fix |
security: |
Security fix or hardening |
docs: |
Documentation only |
test: |
Tests only |
refactor: |
Code change, no behavior change |
ci: |
CI/CD pipeline changes |
chore: |
Dependency updates, tooling |
Examples:
git commit -m "feat: add ad.delegation_abuse with RBCD support"
git commit -m "fix: laps_enum vault.store() not called after LDAP query"
git commit -m "security: narrow DataEncryptor exception catch-all"
Research Tracks
ARES uses formal RFCs to design and coordinate multi-module research efforts.
RFC 001: Linux Active Directory Tradecraft ✅ Completed
All 5 modules from the Linux AD post-exploitation research track are fully implemented and production-ready in ARES v6.0:
linux.sssd_harvest: SSSD LDB database extractionlinux.ccache_hunt: Kerberos ticket cache hunting (file + Kernel Keyring)linux.keytab_abuse: Machine keytab parsing & Silver Ticket generationlinux.samba_secrets: Samba/Winbind machine password extractioncredential.ticket_converter: Bi-directional ccache ↔ kirbi conversion
See the full technical specification: 👉 RFC 001: Linux Active Directory Tradecraft
Want to propose a new research track? Open a Module Development discussion.
Writing a New Module
Every ARES module is a class that extends BaseModule in ares/modules/base.py.
Minimal module skeleton
"""
My Module - category.module_name
MITRE: T1234 - Technique Name
One paragraph: what this module does, what it needs, what it produces.
"""
from __future__ import annotations
from typing import Any
from ares.core.campaign import Severity
from ares.core.logger import audit, get_logger
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
logger = get_logger("ares.modules.category.module_name")
class MyModule(BaseModule):
MODULE_ID = "category.module_name"
MODULE_NAME = "Human Readable Name"
MODULE_CATEGORY = "category" # ad|credential|lateral|windows|linux|cloud|network|recon|exfil|persistence
MODULE_DESCRIPTION = "One line description for ares module list"
OPSEC_LEVEL = OpsecLevel.MEDIUM
REQUIRES = [] # e.g. ["domain_creds"]
OUTPUTS = [] # e.g. ["spn_list"]
MITRE_TECHNIQUES = ["T1234"]
MODULE_TIMEOUT_SECONDS: int | None = None # override if slow (e.g. 300 for dump)
async def validate(self, ctx: "Any") -> None:
"""Pre-flight checks - runs before any network call."""
await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
# Add module-specific checks here
if not ctx.params.get("required_param"):
raise ModuleValidationError(
"category.module_name requires 'required_param'.",
module_id=self.MODULE_ID, field="required_param",
)
async def execute(self, ctx: "Any") -> "ModuleResult":
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={})
target = getattr(ctx, "target", "") or ctx.params.get("target", "")
findings, raw = await self.run(target=target, **ctx.params)
return ModuleResult(
status="success" if findings else "partial",
findings=findings, raw=raw, module_id=self.MODULE_ID,
)
@trace_module("category.module_name")
async def run(self, target: str, **kwargs: Any):
import asyncio
await self.before_request(target, "default")
logger.info("my_module_start", target=target)
audit("my_module", actor="operator", technique="T1234",
source="operator", target=target)
loop = asyncio.get_running_loop()
# All blocking I/O must go in a sync function run via executor
result = await loop.run_in_executor(None, lambda: self._do_work_sync(target))
if result:
self.finding(
title=f"Finding title on {target}",
description="What was found and why it matters.",
severity=Severity.HIGH,
mitre_technique="T1234",
mitre_tactic="Tactic Name",
evidence={"key": "value"},
remediation="How to fix this.",
host=target, confidence=0.9,
)
await self.noise.jitter.sleep()
return self._findings[:], {"target": target, "result": result}
def _do_work_sync(self, target: str) -> bool:
"""Blocking work. Called via run_in_executor - no await here."""
return True
Required patterns
| Pattern | Rule |
|---|---|
| Blocking I/O | Always loop.run_in_executor(None, self._sync_fn) |
| Connection cleanup | conn = None -> try: -> finally: if conn: conn.close() |
| Pagination | while cookie: loop with 1.2.840.113556.1.4.319 OID for LDAP |
| STEALTH block | HIGH_NOISE modules must raise ModuleValidationError in STEALTH |
| dry_run | Always check ctx.dry_run first in execute() |
validate() |
All modules override; cloud/reporting skip super target check |
| Error classification | Classify errors: AuthenticationFailed / HostUnreachable / NetworkError |
File location
ares/modules/<category>/<module_name>.py
Add your module to the __init__.py or ensure PluginLoader picks it up
(it auto-discovers via inspect.getmembers for all BaseModule subclasses).
Testing Requirements
Every new module needs at minimum:
class TestMyModule:
def test_validate_requires_param(self):
"""validate() must raise ModuleValidationError if required param missing."""
def test_dry_run(self):
"""execute() with dry_run=True must return ModuleResult(status='dry_run')."""
def test_module_id_and_opsec(self):
"""MODULE_ID and OPSEC_LEVEL must match declaration."""
def test_error_classification(self):
"""Auth failures must raise AuthenticationFailed, not generic Exception."""
Run tests:
pytest tests/unit/ -v # all unit tests
pytest tests/unit/ -k "MyModule" -v # just your module
pytest tests/unit/ --cov=ares --cov-fail-under=82 -v # with coverage
Pull Request Process
- All pre-commit hooks pass (
pre-commit run --all-files) - Tests pass with
pytest tests/unit/ --cov=ares --cov-fail-under=82 - PR description includes: what changed, why, MITRE reference (for modules)
- Update
CHANGELOG.md- add entry under[Unreleased]section - At least one maintainer review required before merge to
main - Squash merge to
main; no merge commits
Code Guidelines & Conventions
- Python 3.11+ - use
match,|union types,TypeAliaswhere appropriate - Pydantic v2 for all settings and data models
- structlog for all logging - never
print()or stdlibloggingdirectly - asyncio throughout - no blocking calls on the event loop
- type annotations on all public functions - mypy strict enabled
- ruff for linting (replaces flake8, isort, pyupgrade)
- No hardcoded secrets - everything via
.envor env vars
Questions? Start a Discussion or open an issue on GitHub.