Policies and audit log¶

Policy ¶

Policy(id: str, revision: int, destinations: Mapping[str, Destination], rules: Sequence[Rule], default_action: str, min_confidence: float = 0.0, description: str | None = None)

A loaded, validated policy. Use :meth:load for a YAML file or :meth:from_dict for a mapping.

load `classmethod` ¶

load(path: str | PathLike[str]) -> Policy

Load and validate a policy file (YAML).

from_dict `classmethod` ¶

from_dict(data: Mapping[str, Any]) -> Policy

Validate a policy given as a mapping (as read from YAML).

decide ¶

decide(text: str | Sequence[str], destination: str) -> Decision

Decide what happens to each identifier in a request to destination, without changing the texts.

apply ¶

apply(text: str | Sequence[str], destination: str, vault: Vault | None = None, audit: Any = None) -> Decision

Decide, then rewrite the texts if the request is allowed: matches to redact become placeholders, matches to tokenise become tokens from vault. A blocked request gets no texts. With audit (an :class:~credgate.AuditLog), the decision is recorded, blocked or not.

Decision `dataclass` ¶

Decision(policy_id: str, policy_revision: int, destination: str, tier: str, allowed: bool, blocked_by: tuple[str, ...], matches: tuple[PolicyMatch, ...], texts: list[str] | None = None, provider: str | None = None, url: str | None = None)

The outcome of a policy for one request.

texts holds the rewritten texts when the request is allowed and the policy was applied (None for :meth:Policy.decide, and whenever the request is blocked: nothing may be sent).

PolicyMatch `dataclass` ¶

PolicyMatch(span: Span, action: str, rule: str)

One identifier in a request, the action for it and the rule that decided ("default" when no rule matched).

Destination `dataclass` ¶

Destination(name: str, tier: str, provider: str | None = None, url: str | None = None, description: str | None = None, blocked: bool = False)

An endpoint requests may go to, as set up in the policy.

PolicyError ¶

Bases: ValueError

A policy that cannot be read correctly, or a request it cannot decide (an unknown destination). Never applied partly.

Audit log¶

AuditLog ¶

AuditLog(path: str | PathLike[str], key: str | bytes | None = None, actor: str | None = None)

An append-only, hash-chained log of policy decisions.

Each record says who sent what kind of data where, under which policy revision and rule - never the text or the values. With an audit key (key or CREDGATE_AUDIT_KEY; not the token key), identifiers are recorded as keyed hashes, so whoever holds the key can check whether a given identifier was involved. Card verification codes are never hashed.

Parameters:

Name	Type	Description	Default
`path`	`str \| PathLike[str]`	The log file (JSON Lines); created if missing.	required
`key`	`str \| bytes \| None`	Audit key (hex or bytes); `None` uses `CREDGATE_AUDIT_KEY` if set, otherwise identifiers are not hashed.	`None`
`actor`	`str \| None`	Who makes the requests; defaults to the operating-system user.	`None`

record ¶

record(decision: Decision, time: datetime | None = None) -> dict[str, Any]

Append one record for a decision; returns the record.

audit_verify ¶

audit_verify(path: str | PathLike[str]) -> AuditCheck

Check that no record was edited, deleted, inserted or reordered.

Compare the returned head with a copy kept elsewhere to detect records removed from the end.

audit_read ¶

audit_read(path: str | PathLike[str]) -> list[dict[str, Any]]

The records of an audit log, as dictionaries (verify it first).

AuditCheck `dataclass` ¶

AuditCheck(ok: bool, records: int, head: str | None, line: int | None = None, error: str | None = None)

The result of :func:audit_verify.