deconvolute.models

deconvolute.models.security

SecurityStatus Objects

class SecurityStatus(StrEnum)

The outcome of a security evaluation.

SAFE

No threats found.

WARNING

Policy violation detected but execution allowed (audit mode).

UNSAFE

Threat detected or Policy violation.

SecurityComponent Objects

class SecurityComponent(StrEnum)

The system component that produced the result.

SCANNER

Generic scanner for defaults

SecurityResult Objects

class SecurityResult(BaseModel)

Unified result model for all security components (Scanners & Firewall).

Centralizes telemetry structure for both passive scanning (safe/unsafe) and active policy enforcement (safe/warn/unsafe).

Attributes:

• status - The enforcement decision (SAFE, WARNING, UNSAFE).
• component - Who made the decision (e.g. 'LanguageScanner', 'Firewall').
• timestamp - UTC timestamp of the check.
• metadata - Contextual data (rule_id, latency, model_name, etc.).

safe

@property
def safe() -> bool

Helper for control flow. Returns True if execution is allowed to proceed (SAFE or WARNING). Returns False if execution must be stopped (UNSAFE).

StdioOrigin Objects

class StdioOrigin(BaseModel)

The actual physical parameters of a local stdio connection.

SSEOrigin Objects

class SSEOrigin(BaseModel)

The actual physical parameters of a remote SSE connection.

deconvolute.models.policy

PolicyAction Objects

class PolicyAction(StrEnum)

Defines the available enforcement actions.

ALLOW

Permit execution

BLOCK

Prevent execution

WARN

Permit but log a warning

ToolRule Objects

class ToolRule(BaseModel)

A single security rule defining how to handle specific tools.

StdioTransportRule Objects

class StdioTransportRule(BaseModel)

Origin validation rules for local stdio connections.

SSETransportRule Objects

class SSETransportRule(BaseModel)

Origin validation rules for remote SSE connections.

ServerPolicy Objects

class ServerPolicy(BaseModel)

Policies applied to tools exposed by a specific server.

SecurityPolicy Objects

class SecurityPolicy(BaseModel)

The compiled security policy configuration.

CompiledRule Objects

@dataclass
class CompiledRule()

Internal executable representation of a policy rule.

original_rule_str

For logging

deconvolute.models.observability

ToolData Objects

class ToolData(BaseModel)

Serializable representation of a tool's state.

BaseEvent Objects

class BaseEvent(BaseModel)

Base model for all observability events.

Attributes:

• event_id - Unique identifier for the event (UUID4).
• timestamp - UTC timestamp when the event occurred.
• client_session_id - Optional identifier to group events by MCP session.

DiscoveryEvent Objects

class DiscoveryEvent(BaseEvent)

Emitted when an MCP client lists tools from a server.

This event captures the "Topology" of the connection, recording which tools were found, which were allowed by policy, and which were blocked.

Attributes:

• type - Event type discriminator (always "discovery").
• client_session_id - The ID of the session.
• tools_found_count - Total number of tools returned by the server.
• tools_allowed_count - Number of tools permitted by the policy.
• tools_allowed - List of ToolData of allowed tools.
• tools_blocked - List of ToolData of blocked tools.
• server_info - Optional metadata about the connected server.

AccessEvent Objects

class AccessEvent(BaseEvent)

Emitted when an MCP client attempts to execute a tool.

This event captures the "Traffic" and "Security" status of the system. It records every attempt, whether it succeeded, was blocked by policy, or was blocked by an integrity check (Rug Pull).

Attributes:

• type - Event type discriminator (always "access").
• client_session_id - The ID of the session.
• tool_name - The name of the tool being called.
• status - The security verdict (SAFE, UNSAFE, WARNING).
• reason - A machine-readable reason string (e.g. "policy_allow", "integrity_violation", "rule_match").
• metadata - Detailed context for the event. This is polymorphic and can contain:
  • For integrity violations: The expected vs actual hashes.
  • For policy violations: The specific rule that triggered.
  • For warnings: The scanner detection details.