Core Concepts

ATHELOS has a small number of core objects. Understanding how they relate makes everything else obvious.

The hierarchy

Client
  └── Engagement
        ├── Scope items
        ├── Findings
        │     └── Evidence
        ├── Time entries
        ├── Playbook executions
        └── Reports
              └── Delivery links

Client

A Client is an organization you do work for. It holds contact details, billing information, and the history of interactions.

Clients are the top-level container. Everything else belongs to a client eventually — an engagement is run for a client, an invoice is billed to a client, a report is prepared for a client.

Engagement

An Engagement is a single piece of work — a penetration test, a forensic investigation, an incident response. It belongs to exactly one client, has a start and end date, and a type.

Engagements move through a defined lifecycle:

Scoping -> Recon -> Exploitation -> Reporting -> Closed

You advance the phase as work progresses. Each transition is recorded in the audit log.

Scope item

A Scope item is a target — an IP, a domain, an application, a user. It carries a direction: in-scope or out-of-scope. Out-of-scope items are just as important as in-scope ones — they document the boundaries.

Finding

A Finding is a security issue discovered during an engagement. Every finding has:

• Title and description — what the issue is
• Severity — critical, high, medium, low, or informational
• CVSS score and vector — the standardized risk rating
• ATT&CK mapping — one or more technique IDs (T####)
• Impact — what an attacker could do with this
• Remediation — how to fix it
• Status — open, confirmed, false positive, or retested

Findings make up the technical body of a report.

Evidence

Evidence is a file attached to a finding — a screenshot, a packet capture, a log excerpt, a command output. Evidence is stored in MinIO, hashed with SHA-256 for integrity, and linked to the finding it supports.

The hash matters for two reasons: it proves the evidence hasn't been modified since upload, and it satisfies the chain-of-custody requirements that forensic work demands.

Playbook

A Playbook is a methodology checklist — PTES, OWASP WSTG, NIST 800-115, or one of the domain-specific playbooks that ship with ATHELOS. You load a playbook onto an engagement and work through its tasks. Each task can be ticked off, annotated with notes, and linked to findings or evidence.

Playbooks ensure you don't miss a step. They're stored in the knowledge base as articles with structured metadata.

Report

A Report is the deliverable that goes to the client. It's generated from an engagement and pulls in the findings you've selected to include.

Reports have:

• Template — one of seven (pentest, forensics, IR, compliance, purple team, attestation, retest)
• Version — integer, incremented each regeneration
• Sections — executive summary, scope, methodology, findings, plus any special sections the template defines
• Status — draft, in review, or delivered

Once a report is delivered, you can generate a delivery link — a signed, expiring URL that lets the client view the report without logging in. Every view is tracked. The link can be revoked at any time.

Time entry

A Time entry records hours spent on an engagement. It's used for billing and for the financial dashboard's effective hourly rate calculation.

Invoice

An Invoice is generated from an engagement and bills the client. Line items are stored in integer cents, never floats. Payment status is tracked. The financial dashboard aggregates revenue across all invoices.

How it all connects

A typical engagement flow:

1. You add a Client
2. You create an Engagement for that client
3. You define Scope items
4. You load a Playbook
5. You work through tasks, logging Findings and capturing Evidence
6. You log Time entries as you go
7. You generate a Report from the findings
8. You create a Delivery link and send it to the client
9. You generate an Invoice for the engagement

Every step is connected to the previous one. Nothing is entered twice. This is the point of an integrated platform.

Where to go next

• Your first engagement — a full walkthrough
• Managing findings — the details
• Generating reports — from findings to PDF