Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

16.6 KB
Raw Blame
"""
ARES Campaign Checkpoint System
Persists full campaign state to disk for pause/resume and crash recovery.

CLI usage:
    ares campaign pause  <campaign_id>   → saves checkpoint
    ares campaign resume <campaign_id>   → restores and continues

Checkpoint includes:
    - Campaign config + findings so far
    - OperatorSession (all hosts, compromise levels, history)
    - CredentialVault (all credentials, encrypted)
    - GoalEngine plan + completed steps
    - PivotManager tunnels
    - Execution queue (pending tasks)
    - Attack timeline events

Storage:
    ~/.ares/checkpoints/<campaign_id>/<timestamp>.ares_ckpt  (AES-256-GCM)
    ~/.ares/checkpoints/<campaign_id>/latest -> symlink to newest

Security:
    All checkpoints are AES-256-GCM encrypted with the operator's key.
    Legacy Fernet checkpoints are transparently decrypted on load.
    Plaintext secrets never touch disk.
"""
from __future__ import annotations

import json
import os
import time
import uuid
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

from cryptography.fernet import Fernet
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

from ares.core.logger import audit, get_logger

logger = get_logger("ares.checkpoint")

CHECKPOINT_DIR = Path.home() / ".ares" / "checkpoints"
CHECKPOINT_EXT = ".ares_ckpt"


@dataclass
class CheckpointManifest:
    """Metadata stored unencrypted in the checkpoint header."""
    checkpoint_id:   str = field(default_factory=lambda: str(uuid.uuid4())[:8])
    campaign_id:     str = ""
    campaign_name:   str = ""
    operator:        str = ""
    created_at:      float = field(default_factory=time.time)
    schema_version:  str = "1.0"
    ares_version:    str = ""  # Set at creation time from ares.__version__
    hosts_captured:  int = 0
    findings_count:  int = 0
    goal:            str = ""
    goal_achieved:   bool = False
    notes:           str = ""

    def to_dict(self) -> dict[str, Any]:
        return {
            "checkpoint_id":  self.checkpoint_id,
            "campaign_id":    self.campaign_id,
            "campaign_name":  self.campaign_name,
            "operator":       self.operator,
            "created_at":     self.created_at,
            "schema_version": self.schema_version,
            "ares_version":   self.ares_version,
            "hosts_captured": self.hosts_captured,
            "findings_count": self.findings_count,
            "goal":           self.goal,
            "goal_achieved":  self.goal_achieved,
            "notes":          self.notes,
        }


@dataclass
class CheckpointData:
    """Full serialized campaign state."""
    manifest:      CheckpointManifest = field(default_factory=CheckpointManifest)
    campaign_id:   str = ""          # convenience field - mirrors manifest.campaign_id
    vault:         dict[str, Any] = field(default_factory=dict)  # encrypted credential store
    campaign:      dict[str, Any]         = field(default_factory=dict)
    session:       dict[str, Any]         = field(default_factory=dict)  # OperatorSession.snapshot()
    credential_ids: list[str]             = field(default_factory=list)  # vault IDs (secrets excluded)
    pending_tasks: list[dict[str, Any]]   = field(default_factory=list)  # cluster tasks not yet run
    completed_steps: list[str]            = field(default_factory=list)  # module IDs done
    timeline:      list[dict[str, Any]]   = field(default_factory=list)  # attack timeline events
    pivot_tunnels: list[dict[str, Any]]   = field(default_factory=list)  # active tunnels
    extra:         dict[str, Any]         = field(default_factory=dict)

    def __post_init__(self) -> None:
        # Sync campaign_id ↔ manifest
        if self.campaign_id and not self.manifest.campaign_id:
            self.manifest.campaign_id = self.campaign_id
        elif self.manifest.campaign_id and not self.campaign_id:
            self.campaign_id = self.manifest.campaign_id

    def to_dict(self) -> dict[str, Any]:
        return {
            "manifest":       self.manifest.to_dict(),
            "vault":          self.vault,
            "campaign":       self.campaign,
            "session":        self.session,
            "credential_ids": self.credential_ids,
            "pending_tasks":  self.pending_tasks,
            "completed_steps": self.completed_steps,
            "timeline":       self.timeline,
            "pivot_tunnels":  self.pivot_tunnels,
            "extra":          self.extra,
        }


class CheckpointManager:
    """
    Saves and restores campaign state.
    Encrypts all data at rest using AES-256-GCM.
    Legacy Fernet checkpoints are transparently decrypted on load.

    Usage:
        mgr = CheckpointManager(encryption_key)
        ckpt_path = mgr.save(data)
        data = mgr.load(campaign_id)
    """

    # Fixed salt for checkpoint key derivation - deterministic so same key always
    # produces same derived key across restarts (no salt storage required).
    _KDF_SALT = b"ares-checkpoint-manager-v1-salt"
    _KDF_SALT_V2 = b"ares-checkpoint-manager-v2-gcm"

    # AES-GCM nonce length
    _GCM_NONCE_LEN = 12
    # Magic header for v2 checkpoint files (4 bytes)
    _V2_MAGIC = b"ACV2"

    def __init__(self, encryption_key: bytes | str) -> None:
        import base64

        from cryptography.hazmat.primitives import hashes as _hashes
        from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC

        # Normalise to bytes
        if hasattr(encryption_key, "get_secret_value"):
            key_bytes = encryption_key.get_secret_value().encode()
        elif isinstance(encryption_key, str):
            key_bytes = encryption_key.encode()
        elif isinstance(encryption_key, (bytes, bytearray)):
            key_bytes = bytes(encryption_key)
        else:
            raise TypeError(f"encryption_key must be str or bytes, got {type(encryption_key)}")

        # ── v2 AES-256-GCM key derivation (600k iterations) ──
        kdf_v2 = PBKDF2HMAC(
            algorithm=_hashes.SHA256(),
            length=32,
            salt=self._KDF_SALT_V2,
            iterations=600_000,
        )
        self._aesgcm = AESGCM(kdf_v2.derive(key_bytes))

        # ── Legacy Fernet key (100k iterations) for backward-compat decrypt ──
        kdf_legacy = PBKDF2HMAC(
            algorithm=_hashes.SHA256(),
            length=32,
            salt=self._KDF_SALT,
            iterations=100_000,
        )
        derived_legacy = kdf_legacy.derive(key_bytes)
        self._fernet = Fernet(base64.urlsafe_b64encode(derived_legacy))
        CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)

    def _decrypt_checkpoint(self, data: bytes) -> bytes:
        """
        Decrypt a checkpoint blob.
        Tries v2 AES-256-GCM first (magic header 'ACV2'), falls back to Fernet.
        """
        if data[:len(self._V2_MAGIC)] == self._V2_MAGIC:
            nonce_start = len(self._V2_MAGIC)
            nonce_end   = nonce_start + self._GCM_NONCE_LEN
            nonce = data[nonce_start:nonce_end]
            ct    = data[nonce_end:]
            return self._aesgcm.decrypt(nonce, ct, None)
        # Legacy Fernet fallback
        return self._fernet.decrypt(data)

    def save(self, data: CheckpointData, notes: str = "") -> Path:
        """
        Serialize, encrypt, and write checkpoint to disk.
        Returns path to checkpoint file.
        """
        # Always generate a fresh checkpoint_id and timestamp per save
        import uuid as _uuid
        data.manifest.checkpoint_id = str(_uuid.uuid4())[:8]
        data.manifest.created_at    = time.time()
        data.manifest.notes = notes
        raw      = json.dumps(data.to_dict(), default=str).encode()
        nonce    = os.urandom(self._GCM_NONCE_LEN)
        ct       = self._aesgcm.encrypt(nonce, raw, None)
        encrypted = self._V2_MAGIC + nonce + ct

        campaign_dir = CHECKPOINT_DIR / (data.campaign_id or data.manifest.campaign_id)
        campaign_dir.mkdir(parents=True, exist_ok=True)

        ts       = int(data.manifest.created_at)
        ckpt_id  = data.manifest.checkpoint_id
        filename = f"{ts}_{ckpt_id}{CHECKPOINT_EXT}"
        ckpt_path = campaign_dir / filename

        ckpt_path.write_bytes(encrypted)

        # Update "latest" pointer - use a regular file copy (Windows doesn't always support symlinks)
        latest = campaign_dir / f"latest{CHECKPOINT_EXT}"
        try:
            import shutil as _shutil
            _shutil.copy2(ckpt_path, latest)
        except Exception:
            # Fallback: try symlink
            try:
                if latest.is_symlink() or latest.exists():
                    latest.unlink()
                latest.symlink_to(ckpt_path.name)
            except Exception:
                pass

        audit("checkpoint_saved", actor=data.manifest.operator,
              campaign=data.manifest.campaign_id,
              checkpoint_id=ckpt_id,
              path=str(ckpt_path))
        logger.info("checkpoint_saved",
                    campaign=data.manifest.campaign_id,
                    checkpoint_id=ckpt_id,
                    size_kb=len(encrypted) // 1024)
        return ckpt_path

    def load(self, campaign_id: str, checkpoint_id: str = "latest") -> CheckpointData:
        """
        Decrypt and deserialize the latest (or specific) checkpoint.
        Raises FileNotFoundError if no checkpoint exists.
        """
        campaign_dir = CHECKPOINT_DIR / campaign_id
        if not campaign_dir.exists():
            raise FileNotFoundError(f"No checkpoints for campaign {campaign_id!r}")

        if checkpoint_id == "latest":
            path = campaign_dir / "latest.ares_ckpt"
            if path.is_symlink():
                path = path.resolve()
            else:
                # Fallback: newest file
                files = sorted(campaign_dir.glob(f"*{CHECKPOINT_EXT}"),
                                key=lambda p: p.stat().st_mtime, reverse=True)
                if not files:
                    raise FileNotFoundError(f"No checkpoint files in {campaign_dir}")
                path = files[0]
        else:
            matches = list(campaign_dir.glob(f"*{checkpoint_id}*{CHECKPOINT_EXT}"))
            if not matches:
                raise FileNotFoundError(f"Checkpoint {checkpoint_id!r} not found")
            path = matches[0]

        encrypted = path.read_bytes()
        raw       = self._decrypt_checkpoint(encrypted)
        d         = json.loads(raw)

        manifest = CheckpointManifest(**d["manifest"])
        data = CheckpointData(
            manifest        = manifest,
            campaign_id     = manifest.campaign_id,
            vault           = d.get("vault", {}),
            campaign        = d.get("campaign", {}),
            session         = d.get("session", {}),
            credential_ids  = d.get("credential_ids", []),
            pending_tasks   = d.get("pending_tasks", []),
            completed_steps = d.get("completed_steps", []),
            timeline        = d.get("timeline", []),
            pivot_tunnels   = d.get("pivot_tunnels", []),
            extra           = d.get("extra", {}),
        )
        audit("checkpoint_loaded", actor="engine",
              campaign=campaign_id, checkpoint_id=manifest.checkpoint_id)
        logger.info("checkpoint_loaded",
                    campaign=campaign_id, checkpoint_id=manifest.checkpoint_id,
                    hosts=manifest.hosts_captured, findings=manifest.findings_count)
        return data

    def list_checkpoints(self, campaign_id: str) -> list[dict[str, Any]]:
        """Return metadata for all checkpoints of a campaign."""
        campaign_dir = CHECKPOINT_DIR / campaign_id
        if not campaign_dir.exists():
            return []
        results = []
        files = []
        for f in campaign_dir.glob(f"*{CHECKPOINT_EXT}"):
            if f.name.startswith("latest"):
                continue
            try:
                files.append((f.stat().st_mtime, f))
            except (OSError, FileNotFoundError):
                pass  # broken symlink or deleted file
        for _, f in sorted(files, key=lambda t: -t[0]):
            try:
                enc = f.read_bytes()
                raw = self._decrypt_checkpoint(enc)
                d   = json.loads(raw)
                results.append(d["manifest"])
            except (ValueError, KeyError, OSError):
                results.append({"file": f.name, "error": "decrypt_failed"})
        return results

    def delete_checkpoint(self, campaign_id: str, checkpoint_id: str) -> bool:
        """Delete a specific checkpoint file."""
        campaign_dir = CHECKPOINT_DIR / campaign_id
        matches = list(campaign_dir.glob(f"*{checkpoint_id}*{CHECKPOINT_EXT}"))
        if not matches:
            return False
        for f in matches:
            f.unlink()
        logger.info("checkpoint_deleted", campaign=campaign_id, checkpoint_id=checkpoint_id)
        return True

    def purge_old(self, campaign_id: str, keep_last: int = 5) -> int:
        """Delete old checkpoints, keeping the N most recent."""
        campaign_dir = CHECKPOINT_DIR / campaign_id
        if not campaign_dir.exists():
            return 0
        files = sorted(
            [f for f in campaign_dir.glob(f"*{CHECKPOINT_EXT}")
             if "latest" not in f.name],
            key=lambda p: p.stat().st_mtime, reverse=True,
        )
        to_delete = files[keep_last:]
        for f in to_delete:
            f.unlink()
        if to_delete:
            logger.info("checkpoints_purged", campaign=campaign_id, deleted=len(to_delete))
        return len(to_delete)


def _build_checkpoint_full(
    campaign_id:     str,
    campaign_name:   str,
    operator:        str,
    session_snapshot: dict[str, Any],
    findings:        list[Any],
    pending_tasks:   list[dict[str, Any]] | None = None,
    completed_steps: list[str] | None = None,
    timeline:        list[dict[str, Any]] | None = None,
    pivot_summary:   list[dict[str, Any]] | None = None,
    goal:            str = "",
    goal_achieved:   bool = False,
    extra:           dict[str, Any] | None = None,
) -> CheckpointData:
    """
    Helper to build a CheckpointData from live engine state.
    Call before ares campaign pause or on crash handler.
    """
    from ares.__version__ import __version__ as _ares_ver
    manifest = CheckpointManifest(
        campaign_id    = campaign_id,
        campaign_name  = campaign_name,
        operator       = operator,
        ares_version   = _ares_ver,
        hosts_captured = len(session_snapshot.get("hosts", {})),
        findings_count = len(findings),
        goal           = goal,
        goal_achieved  = goal_achieved,
    )
    return CheckpointData(
        manifest        = manifest,
        session         = session_snapshot,
        campaign        = {"id": campaign_id, "name": campaign_name},
        credential_ids  = [],   # IDs only - secrets stay in vault
        pending_tasks   = pending_tasks or [],
        completed_steps = completed_steps or [],
        timeline        = timeline or [],
        pivot_tunnels   = pivot_summary or [],
        extra           = extra or {},
    )


def build_checkpoint(
    session_or_campaign_id: "Any" = None,
    vault: "Any | None" = None,
    **kwargs: "Any",
) -> "CheckpointData":
    """
    Flexible checkpoint builder. Accepts:
      build_checkpoint(session)                           - unit test style
      build_checkpoint(campaign_id=..., operator=..., ...) - integration style
    """
    from ares.state.target_state import OperatorSession

    # Style 1: first arg is an OperatorSession
    if isinstance(session_or_campaign_id, OperatorSession):
        sess = session_or_campaign_id
        return CheckpointData(
            campaign_id = sess.campaign_id,
            session     = sess.snapshot(),
            vault       = vault if isinstance(vault, dict) else {},
        )

    # Style 2: kwargs-only (integration test style)
    campaign_id   = kwargs.get("campaign_id") or (str(session_or_campaign_id) if session_or_campaign_id else "")
    campaign_name = kwargs.get("campaign_name", "")
    operator      = kwargs.get("operator", "unknown")
    goal          = kwargs.get("goal", "")
    goal_achieved = kwargs.get("goal_achieved", False)
    session_snap  = kwargs.get("session_snapshot", {})
    findings      = kwargs.get("findings", [])

    manifest = CheckpointManifest(
        campaign_id   = campaign_id,
        campaign_name = campaign_name,
        operator      = operator,
        goal          = goal,
        goal_achieved = goal_achieved,
        findings_count = len(findings),
    )
    return CheckpointData(
        manifest    = manifest,
        campaign_id = campaign_id,
        session     = session_snap,
        vault       = vault if isinstance(vault, dict) else {},
    )