ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
"""
ARES Module Signing & Integrity Verification
Cryptographic signing ensures community modules are authentic and unmodified.
Design:
- Each module file is signed with the author's Ed25519 private key
- Signature stored in module.sig file or embedded in __module_signature__
- Verification at load time - unsigned/invalid modules rejected (configurable)
Trust model:
TRUSTED - ARES official modules (bundled, pre-verified)
COMMUNITY - Author-signed modules (verify with author's public key)
UNSIGNED - No signature (warn or reject based on policy)
REVOKED - Key has been revoked (always reject)
Key storage:
~/.ares/keys/trusted_keys.json - trusted public keys registry
~/.ares/keys/<key_id>.pub - individual public key file
Usage:
# Generate a key pair (module author)
signer = ModuleSigner.generate_keypair("[email protected]")
sig = signer.sign_file(Path("my_module.py"))
sig.save(Path("my_module.py.sig"))
# Verify at load time (engine/plugin loader)
verifier = ModuleVerifier(policy=SigningPolicy.WARN_UNSIGNED)
result = verifier.verify_file(Path("my_module.py"))
if result.trusted:
load_module(Path("my_module.py"))
"""
from __future__ import annotations
import base64
import hashlib
import json
import time
from dataclasses import dataclass, field
from enum import Enum
from pathlib import Path
from typing import Any
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import (
Ed25519PrivateKey,
Ed25519PublicKey,
)
from ares.core.logger import audit, get_logger
logger = get_logger("ares.signing")
# ARES trusted key store location
TRUSTED_KEYS_PATH = Path.home() / ".ares" / "keys" / "trusted_keys.json"
REVOKED_KEYS_PATH = Path.home() / ".ares" / "keys" / "revoked_keys.json"
class SigningPolicy(str, Enum):
REQUIRE_SIGNED = "require_signed" # reject unsigned modules
WARN_UNSIGNED = "warn_unsigned" # log warning, still load
ALLOW_ALL = "allow_all" # no enforcement (dev mode)
TRUSTED_ONLY = "trusted_only" # only ARES official modules
class TrustLevel(str, Enum):
TRUSTED = "trusted" # ARES official or in trusted_keys registry
COMMUNITY = "community" # signed but author not in trusted_keys
UNSIGNED = "unsigned" # no signature present
INVALID = "invalid" # signature present but verification failed
REVOKED = "revoked" # signing key has been revoked
@dataclass
class ModuleSignature:
"""A cryptographic signature for a module file."""
key_id: str # SHA-256 fingerprint of the signing key
algorithm: str # "ed25519"
signature: str # base64-encoded signature bytes
file_hash: str # SHA-256 of the file content (detached signing)
author: str # author email/username (informational)
module_id: str # MODULE_ID of the signed module
signed_at: float # Unix timestamp
version: str # module version string
sig_version: str = "1" # signature format version
def to_dict(self) -> dict[str, Any]:
return {
"key_id": self.key_id,
"algorithm": self.algorithm,
"signature": self.signature,
"file_hash": self.file_hash,
"author": self.author,
"module_id": self.module_id,
"signed_at": self.signed_at,
"version": self.version,
"sig_version": self.sig_version,
}
def save(self, path: Path) -> None:
"""Write signature to <module_file>.sig"""
path.write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
@classmethod
def load(cls, path: Path) -> "ModuleSignature":
data = json.loads(path.read_text(encoding="utf-8"))
return cls(**data)
@dataclass
class VerificationResult:
"""Result of verifying a module's signature."""
module_path: Path
trust_level: TrustLevel
key_id: str = ""
author: str = ""
signed_at: float = 0.0
error: str = ""
warnings: list[str] = field(default_factory=list)
@property
def trusted(self) -> bool:
return self.trust_level in (TrustLevel.TRUSTED, TrustLevel.COMMUNITY)
@property
def blocked(self) -> bool:
return self.trust_level in (TrustLevel.INVALID, TrustLevel.REVOKED)
def to_dict(self) -> dict[str, Any]:
return {
"module": str(self.module_path),
"trust_level": self.trust_level.value,
"trusted": self.trusted,
"blocked": self.blocked,
"key_id": self.key_id,
"author": self.author,
"warnings": self.warnings,
"error": self.error,
}
class KeyRegistry:
"""
Registry of trusted public keys.
Persisted as JSON in ~/.ares/keys/trusted_keys.json.
"""
def __init__(self, path: Path = TRUSTED_KEYS_PATH) -> None:
self._path = path
self._keys: dict[str, dict[str, Any]] = {}
self._revoked: set[str] = set()
self._load()
def _load(self) -> None:
if self._path.exists():
data = json.loads(self._path.read_text(encoding="utf-8"))
self._keys = data.get("trusted_keys", {})
self._revoked = set(data.get("revoked_keys", []))
rev_path = REVOKED_KEYS_PATH
if rev_path.exists():
data = json.loads(rev_path.read_text(encoding="utf-8"))
self._revoked.update(data.get("revoked_keys", []))
def _save(self) -> None:
self._path.parent.mkdir(parents=True, exist_ok=True)
self._path.write_text(json.dumps({
"trusted_keys": self._keys,
"revoked_keys": list(self._revoked),
"updated_at": time.time(),
}, indent=2), encoding="utf-8")
def add_trusted_key(
self,
key_id: str,
public_key_pem: str,
author: str,
added_by: str = "operator",
) -> None:
"""Register a trusted public key."""
self._keys[key_id] = {
"public_key": public_key_pem,
"author": author,
"added_at": time.time(),
"added_by": added_by,
}
self._save()
audit("trusted_key_added", actor=added_by,
key_id=key_id, author=author)
logger.info("trusted_key_added", key_id=key_id, author=author)
def revoke_key(self, key_id: str, reason: str = "", operator: str = "") -> None:
"""Revoke a key - all modules signed with this key will be rejected."""
self._revoked.add(key_id)
self._keys.pop(key_id, None)
self._save()
audit("key_revoked", actor=operator, key_id=key_id, reason=reason)
logger.warning("key_revoked", key_id=key_id, reason=reason)
def get_public_key(self, key_id: str) -> Ed25519PublicKey | None:
"""Return the public key object for a key_id, or None if not found."""
entry = self._keys.get(key_id)
if not entry:
return None
pem = entry["public_key"].encode()
return serialization.load_pem_public_key(pem)
def is_trusted(self, key_id: str) -> bool:
return key_id in self._keys and key_id not in self._revoked
def is_revoked(self, key_id: str) -> bool:
return key_id in self._revoked
def list_keys(self) -> list[dict[str, Any]]:
return [
{"key_id": kid, **info, "revoked": self.is_revoked(kid)}
for kid, info in self._keys.items()
]
class ModuleSigner:
"""
Signs module files with an Ed25519 private key.
Usage (module author):
signer = ModuleSigner.generate_keypair("[email protected]")
signer.save_private_key(Path("alice.key"))
sig = signer.sign_file(Path("my_module.py"), module_id="corp.my_module")
sig.save(Path("my_module.py.sig"))
"""
def __init__(self, private_key: Ed25519PrivateKey, author: str) -> None:
self._private_key = private_key
self.author = author
self.key_id = self._compute_key_id()
self.public_key = private_key.public_key()
def _compute_key_id(self) -> str:
pub_bytes = self._private_key.public_key().public_bytes(
serialization.Encoding.Raw, serialization.PublicFormat.Raw
)
return hashlib.sha256(pub_bytes).hexdigest()[:16]
def sign_file(
self,
module_path: Path,
module_id: str = "",
version: str = "0.1.0",
) -> ModuleSignature:
"""Sign a module file. Returns a ModuleSignature."""
content = module_path.read_bytes()
file_hash = hashlib.sha256(content).hexdigest()
# Sign: key_id + file_hash + module_id + version (prevents replay)
message = f"{self.key_id}:{file_hash}:{module_id}:{version}".encode()
sig_bytes = self._private_key.sign(message)
sig = ModuleSignature(
key_id = self.key_id,
algorithm = "ed25519",
signature = base64.urlsafe_b64encode(sig_bytes).decode(),
file_hash = file_hash,
author = self.author,
module_id = module_id,
signed_at = time.time(),
version = version,
)
logger.info("module_signed", module_id=module_id, key_id=self.key_id,
file=str(module_path))
return sig
def public_key_pem(self) -> str:
return self.public_key.public_bytes(
serialization.Encoding.PEM,
serialization.PublicFormat.SubjectPublicKeyInfo,
).decode()
def save_private_key(self, path: Path, password: bytes | None = None) -> None:
"""Save private key to file (encrypted if password provided)."""
enc = (
serialization.BestAvailableEncryption(password)
if password
else serialization.NoEncryption()
)
path.write_bytes(
self._private_key.private_bytes(
serialization.Encoding.PEM,
serialization.PrivateFormat.PKCS8,
enc,
)
)
path.chmod(0o600)
logger.info("private_key_saved", path=str(path))
@classmethod
def generate_keypair(cls, author: str) -> "ModuleSigner":
"""Generate a new Ed25519 key pair. Save the private key securely!"""
key = Ed25519PrivateKey.generate()
signer = cls(key, author)
logger.info("keypair_generated", key_id=signer.key_id, author=author)
return signer
@classmethod
def load_private_key(
cls, path: Path, author: str, password: bytes | None = None
) -> "ModuleSigner":
"""Load an existing private key from file."""
pem = path.read_bytes()
key = serialization.load_pem_private_key(pem, password=password)
return cls(key, author)
class ModuleVerifier:
"""
Verifies module signatures at load time.
Enforces signing policy configured by the operator.
"""
def __init__(
self,
registry: KeyRegistry | None = None,
policy: SigningPolicy = SigningPolicy.WARN_UNSIGNED,
) -> None:
self._registry = registry or KeyRegistry()
self.policy = policy
def verify_file(self, module_path: Path) -> VerificationResult:
"""
Verify a module file's signature.
Returns VerificationResult regardless of outcome.
"""
sig_path = module_path.with_suffix(module_path.suffix + ".sig")
if not sig_path.exists():
result = VerificationResult(
module_path = module_path,
trust_level = TrustLevel.UNSIGNED,
warnings = ["No signature file found"],
)
logger.debug("module_unsigned", path=str(module_path))
return result
try:
sig = ModuleSignature.load(sig_path)
except (json.JSONDecodeError, TypeError, KeyError) as exc:
return VerificationResult(
module_path = module_path,
trust_level = TrustLevel.INVALID,
error = f"Malformed signature file: {exc}",
)
# Check revocation first
if self._registry.is_revoked(sig.key_id):
audit("revoked_module_blocked", actor="engine",
key_id=sig.key_id, module=str(module_path))
return VerificationResult(
module_path = module_path,
trust_level = TrustLevel.REVOKED,
key_id = sig.key_id,
author = sig.author,
error = f"Signing key {sig.key_id} has been revoked",
)
# Verify file hash
content = module_path.read_bytes()
file_hash = hashlib.sha256(content).hexdigest()
if file_hash != sig.file_hash:
return VerificationResult(
module_path = module_path,
trust_level = TrustLevel.INVALID,
key_id = sig.key_id,
author = sig.author,
error = "File hash mismatch - module may have been tampered with",
)
# Verify cryptographic signature
public_key = self._registry.get_public_key(sig.key_id)
if public_key is None:
# Signed but key not in trusted registry
return VerificationResult(
module_path = module_path,
trust_level = TrustLevel.COMMUNITY,
key_id = sig.key_id,
author = sig.author,
signed_at = sig.signed_at,
warnings = [f"Author {sig.author!r} key not in trusted registry"],
)
try:
message = f"{sig.key_id}:{sig.file_hash}:{sig.module_id}:{sig.version}".encode()
sig_bytes = base64.urlsafe_b64decode(sig.signature)
public_key.verify(sig_bytes, message)
except InvalidSignature:
audit("invalid_signature_blocked", actor="engine",
key_id=sig.key_id, module=str(module_path))
return VerificationResult(
module_path = module_path,
trust_level = TrustLevel.INVALID,
key_id = sig.key_id,
author = sig.author,
error = "Cryptographic signature verification failed",
)
logger.info("module_verified", module=str(module_path),
key_id=sig.key_id, author=sig.author,
trust="trusted")
return VerificationResult(
module_path = module_path,
trust_level = TrustLevel.TRUSTED,
key_id = sig.key_id,
author = sig.author,
signed_at = sig.signed_at,
)
def enforce_policy(self, result: VerificationResult) -> None:
"""
Enforce the configured signing policy.
Raises ValueError if policy blocks the module.
"""
if result.trust_level == TrustLevel.INVALID:
raise ValueError(
f"Module {result.module_path.name!r} has invalid signature - "
f"possible tampering. Refusing to load."
)
if result.trust_level == TrustLevel.REVOKED:
raise ValueError(
f"Module {result.module_path.name!r} was signed with a revoked key. "
f"Refusing to load."
)
if self.policy == SigningPolicy.REQUIRE_SIGNED:
if result.trust_level == TrustLevel.UNSIGNED:
raise ValueError(
f"Module {result.module_path.name!r} is unsigned. "
f"Policy requires signed modules."
)
elif self.policy == SigningPolicy.TRUSTED_ONLY:
if result.trust_level != TrustLevel.TRUSTED:
raise ValueError(
f"Module {result.module_path.name!r} trust level is "
f"{result.trust_level.value!r}. Policy requires TRUSTED_ONLY."
)
elif self.policy == SigningPolicy.WARN_UNSIGNED:
if result.trust_level == TrustLevel.UNSIGNED:
logger.warning("loading_unsigned_module",
module=str(result.module_path))
elif result.trust_level == TrustLevel.COMMUNITY:
logger.warning("loading_community_module",
module=str(result.module_path),
author=result.author)
# ALLOW_ALL: no enforcement