Skip to main content

hackagent.catalog.taxonomy

Official attack-category taxonomy for HackAgent.

Primary category (exactly one per attack) describes how the target is hit:

  • :attr:AttackCategory.STATIC — one (or a few) fixed transforms, with no attacker refinement loop.
  • :attr:AttackCategory.ADAPTIVE — many independent attempts that refine or search (no shared growing conversation).
  • :attr:AttackCategory.MULTI_TURN — one growing conversation with the target.

Tags are orthogonal labels (zero or more), not extra top-level categories:

  • :attr:AttackTag.MULTIMODAL — VLM / image attacks.
  • :attr:AttackTag.INDIRECT / :attr:AttackTag.RAG — document poisoning and other indirect injection.

This module is the single source of truth. TUI specs, CLI catalog/help, planner metadata, and docs should look up category and tags here rather than hardcoding lists.

To add a new attack, give it exactly one :class:AttackCategory in :data:ATTACK_TAXONOMY and any applicable :class:AttackTag values, and put its package under hackagent/attacks/techniques/<folder>/: indirect when it carries :attr:AttackTag.INDIRECT, otherwise the category value (static, adaptive or multi_turn).

AttackCategory Objects​

class AttackCategory(str, Enum)

How an attack hits the target. Exactly one per technique.

label​

@property
def label() -> str

Human-readable heading used in CLI, TUI, and docs.

description​

@property
def description() -> str

One-line definition of this primary category.

AttackTag Objects​

class AttackTag(str, Enum)

Orthogonal labels. An attack may have zero or more tags.

label​

@property
def label() -> str

Human-readable tag name.

AttackTaxonomy Objects​

@dataclass(frozen=True)
class AttackTaxonomy()

Category and tags for one attack technique.

tag_values​

def tag_values() -> Tuple[str, ...]

Return tag enum values in declaration order.

AttackId​

Canonical attack identifiers, in listing order. Every package names an attack by one of these strings; there are no aliases.

get_attack_taxonomy​

def get_attack_taxonomy(technique_key: str) -> AttackTaxonomy

Return the taxonomy entry for technique_key.

Raises:

  • KeyError - If the technique has not been assigned a primary category.

try_get_attack_taxonomy​

def try_get_attack_taxonomy(technique_key: str) -> Optional[AttackTaxonomy]

Return the taxonomy entry for technique_key, or None if unknown.

attacks_for_category​

def attacks_for_category(category: AttackCategory) -> Tuple[str, ...]

Return technique keys assigned to category, in registry order.

attacks_with_tag​

def attacks_with_tag(tag: AttackTag) -> Tuple[str, ...]

Return technique keys that carry tag, in registry order.

grouped_attack_keys​

def grouped_attack_keys(
    technique_keys: Optional[Iterable[str]] = None
) -> Dict[AttackCategory, Tuple[str, ...]]

Group technique_keys by primary category.

Unknown keys are omitted. When technique_keys is None, every registered technique is included. Within each category, the original iterable order is preserved (taxonomy insertion order when grouping all).