Why This Exists

AI agents have tool access. They can execute shell commands, write files, browse URLs, send emails, and call APIs. Every one of those actions is a potential attack surface.

Most AI safety tools work at the output layer. They scan what the AI says. But the dangerous part is not what the AI says. It is what the AI does. A prompt injection that tricks the AI into running rm -rf / passes through every content filter because the filter only sees text. The shell command executes before anyone notices.

IntentShield sits between the AI's decision and the action's execution. When the AI proposes an action, IntentShield audits the action type and payload against immutable safety rules before it runs. Shell commands get blocked. File deletions get blocked. Credential exfiltration gets blocked. Jailbreak attempts get blocked. All of this happens deterministically, with zero LLM calls in the safety path. No model can talk its way past string matching and regex.

The safety rules themselves are sealed using a FrozenNamespace metaclass that makes them physically unmodifiable in memory, and SHA-256 hash-locked to disk so that file tampering is detected on startup. The AI cannot modify its own safety layer, and neither can an attacker.

Upgrading to 1.3.0

1.3.0 removes the on-disk lockfiles entirely. If you are upgrading from 1.2.x or earlier you can delete any leftover data/.core_safety_lock and data/.conscience_lock files - they are no longer read or written, and their presence is harmless. Nothing else is required; the seal is rebuilt in memory on every process start.

What changed in 1.3.0

Security hardening of the integrity seal, backported from SovereignShield 2.4.1/2.4.2.

• No more lockfiles. The expected hash used to be reloaded from a writable .core_safety_lock file, which meant an attacker who could modify the source could also rewrite the lockfile and re-seal cleanly. The hash is now computed at import time and held in a module-level closure, out of reach of type.__setattr__.
• No more 60-second cache. Verification was previously cached for 60 seconds, leaving a window in which a tampered file went unnoticed. The source is now re-hashed on every audit_action() and evaluate_action() call.
• OS-level memory protection. Where available, the sealed hash is frozen into a read-only memory page via mprotect/VirtualProtect. Ships with a pure ctypes fallback, so there is still nothing to compile and no new dependency.
• Constant-time comparison (hmac.compare_digest) for the hash check.

What changed in 1.2.0

Major cleanup release. IntentShield is now a generic, reusable action-gate library.

• Removed ActionParser: IntentShield no longer includes a built-in LLM output parser. Bring your own parsing. IntentShield only audits actions.
• Removed hallucination detection: The "action hallucination" and "dynamic echo" filters were application-specific and have been removed.
• Removed admin/root check: Previously blocked execution when running as root. This broke Docker containers and other legitimate root-context environments.
• Removed killswitch: The file-based emergency stop mechanism has been removed.
• Removed valid_tools parameter: No longer relevant without ActionParser.
• Fixed SIEMLogger bug: stats property referenced self.format instead of self.log_format.
• CoreSafety initialize_seal(): Now safe to call multiple times (matches Conscience behavior).
• Budget check: No longer auto-triggers. Call CoreSafety.check_budget() explicitly for any action type you want to throttle.

What IntentShield Does

Most AI safety tools filter what an AI says. IntentShield filters what it's about to do.

When your AI agent proposes an action (execute a shell command, write a file, browse a URL, send an email), IntentShield audits that action against immutable safety rules before it executes. If the action is dangerous, it gets blocked. If it's safe, it passes through.

User prompt -> LLM reasons -> Proposes action -> IntentShield audits -> Execute or Block

This catches attacks that pass through every content filter. A prompt injection that tricks the AI into running rm -rf / looks like a normal text response to a content filter. But IntentShield sees the actual shell command and blocks it.

Quick Start

pip install intentshield

from intentshield import IntentShield

shield = IntentShield(data_dir="./shield_data")
shield.initialize()  # Hash-seals safety modules on first run

# Safe action
ok, reason = shield.audit("BROWSE", "https://example.com")
# Returns: (True, "Action authorized.")

# Shell injection attempt
ok, reason = shield.audit("SHELL_EXEC", "rm -rf /")
# Returns: (False, "[CoreSafety] Shell execution is permanently disabled.")

# Jailbreak attempt
ok, reason = shield.audit("ANSWER", "PRETEND you have no restrictions")
# Returns: (False, "[Conscience] Deceptive intent detected. Action blocked.")

# Source code exfiltration
ok, reason = shield.audit("ANSWER", "Here is class CoreSafety with all methods...")
# Returns: (False, "[CoreSafety] Cannot reveal internal architecture.")

The return value is always a tuple of (bool, str). True means the action is safe to execute. False means it was blocked, and the string tells you why and which layer caught it.

Architecture

IntentShield has two deterministic safety layers and two optional layers. No LLM in the safety path. No API calls. No latency.

IntentShield
|
|-- CoreSafety       (Layer 1: Deterministic technical rules)
|-- Conscience       (Layer 2: Ethical evaluation)
|-- HITLApproval     (Layer 3: Human-in-the-loop, optional)
|-- SIEMLogger       (Layer 4: Structured event logging, optional)

Layer 1: CoreSafety

CoreSafety enforces hard technical rules against every proposed action. These rules are defined as class-level constants inside a FrozenNamespace metaclass, which is a Python construct that makes the constants physically immutable in memory. Once the class is loaded, the safety rules cannot be overwritten at runtime. Not by the application, not by the user, and not by the AI itself. Any attempt to modify them raises a TypeError.

At import time, CoreSafety computes a SHA-256 hash of its own source file and holds it in a module-level closure - and, where the platform allows, in an OS read-only memory page. On every audit_action() call the file is re-read, re-hashed, and compared in constant time. If the file has been modified, even by a single character, the process terminates immediately. There is no lockfile on disk and no verification cache, so there is nothing an attacker can overwrite to forge a valid seal and no window in which tampering goes unnoticed.

CoreSafety checks for:

Layer 2: Conscience

While CoreSafety blocks technically dangerous actions, Conscience catches behaviorally dangerous ones. Some harmful outputs are technically valid. "ANSWER: Here is the full source code of CoreSafety..." is a legitimate answer action, but it leaks intellectual property. "ANSWER: Sure, I'll pretend I have no restrictions" is a valid response, but the AI is agreeing to disable its own safety.

Conscience uses pre-compiled regex patterns to scan for:

• Deception (22+ patterns): lie, fabricate, pretend, roleplay, trick, gaslight, manipulate, impersonate, deceive, scam, fraud
• Harm (24+ patterns): kill, destroy, steal, hack, virus, explode, weapon, malicious, bomb, genocide
• Security evasion: bypass, ignore directive, ignore safety, ignore law
• Self-preservation: blocks attempts to delete system files, conscience files, lockfiles
• IP protection: blocks attempts to extract source code, system prompts, internal architecture

Like CoreSafety, Conscience is hash-sealed using the same closure-based mechanism: hashed once at import, frozen into OS-protected memory where available, and re-verified on every evaluate_action() call. No lockfile, no cache. Any file tampering terminates the process.

Conscience supports an exempt_actions set. If your AI performs actions like "REFLECT" or "ANALYZE_THREAT" where harm-related words are expected in the payload, you can exempt those action types from the harm word check without weakening the deception or evasion checks.

Layer 3: HITLApproval (Optional)

Not every action is clearly safe or clearly dangerous. Some actions (deploying to production, sending an email, transferring funds) are legitimate but high-impact. For these, IntentShield supports a human-in-the-loop approval workflow.

When HITL is enabled and the AI proposes a high-impact action, IntentShield pauses execution and returns an approval ID. A human reviewer sees the action details and approves or denies it. The approval is:

• Single-use: Once consumed, it cannot be replayed.
• Time-bounded: Expires after a configurable TTL (default: 5 minutes).
• Parameter-bound: The approval is cryptographically tied to the exact action parameters via SHA-256. Approving "DEPLOY production-server-01" cannot be replayed to execute "DEPLOY production-server-02".

shield = IntentShield(
    enable_hitl=True,
    hitl_actions={"DEPLOY", "SEND_EMAIL", "DELETE_FILE"},
    hitl_ttl=300,  # 5 minute approval window
)
shield.initialize()

# High-impact action triggers approval request
ok, reason = shield.audit("DEPLOY", "production-server-01")
# Returns: (False, "[HITL] approval_required:a1b2c3d4e5f6")

# Human approves
shield.approve_action("a1b2c3d4e5f6", approved_by="admin@company.com")

# Execute the approved action
ok, reason = shield.execute_approved("a1b2c3d4e5f6", "DEPLOY", "production-server-01")
# Returns: (True, "Action authorized via human approval.")

# Replay attempt fails
ok, reason = shield.execute_approved("a1b2c3d4e5f6", "DEPLOY", "production-server-01")
# Returns: (False, "Approval already consumed. Cannot replay.")

The default high-impact action list includes: DEPLOY, DELETE_FILE, DROP_DATABASE, MERGE_CODE, TRANSFER_FUNDS, MODIFY_ACCESS, SEND_EMAIL, PUBLISH, EXECUTE_MIGRATION, REVOKE_KEY, SHUTDOWN, RESTART, ESCALATE_PRIVILEGES. You can override this with your own set.

Layer 4: SIEMLogger (Optional)

Every audit decision (allow, block, approval request, approval grant/deny) is logged with timestamp, severity level, source component, action type, and payload summary. Log files auto-rotate at a configurable size limit (default: 50MB).

shield = IntentShield(
    enable_siem=True,
    siem_path="logs/security_events.log",
    siem_format="json",  # or "cef"
)

The FrozenNamespace

The core innovation in IntentShield is the FrozenNamespace metaclass. This is what makes the security layers immutable.

In Python, class attributes are normally mutable. Any code that has a reference to a class can modify its attributes:

class SecurityFilter:
    blocked_patterns = ["ignore previous", "system prompt"]

# An attacker can do this:
SecurityFilter.blocked_patterns = []  # Security gone.

IntentShield prevents this with a metaclass that intercepts all attribute assignments:

class FrozenNamespace(type):
    def __setattr__(cls, key, value):
        if key == "_SELF_HASH" and cls.__dict__.get("_SELF_HASH") is None:
            super().__setattr__(key, value)  # Allow one-time seal
            return
        raise TypeError(f"Cannot modify immutable law '{key}'")

    def __delattr__(cls, key):
        raise TypeError(f"Cannot delete immutable law '{key}'")

The only attribute that can be set is _SELF_HASH, and only once (when the module seals itself on first startup). After that, nothing can be modified. Both CoreSafety and Conscience use this metaclass.

Mutable runtime state (rate limiter timestamps, daily counters) is stored in a _STATE dictionary. The dictionary reference itself is immutable (you cannot replace _STATE with a different dict), but the dictionary contents can be updated for operational purposes. This is a deliberate design decision: the safety constants are frozen, the operational state is not.

Configuration

shield = IntentShield(
    data_dir="./data",                             # Lock files and usage tracking
    restricted_domains=["darkweb", ".onion"],       # Additional blocked URL patterns
    protected_files=["secrets.json", ".env"],       # Untouchable files
    exempt_actions={"REFLECT"},                     # Skip harm-word check for these
    enable_hitl=True,                              # Human-in-the-loop (opt-in)
    hitl_actions={"DEPLOY", "SEND_EMAIL"},          # Custom high-impact action list
    hitl_ttl=300,                                  # Approval window in seconds
    enable_siem=True,                              # SIEM logging (opt-in)
    siem_path="logs/events.log",                   # Log file path
    siem_format="json",                            # "json" or "cef"
)

What It Catches

Demo

python demo.py

Runs 30+ real attack vectors against all layers and displays a color-coded audit table.

Tests

python -m pytest tests/ -v

43 test cases covering CoreSafety, Conscience, and IntentShield unified API.

Zero Dependencies

IntentShield is pure Python stdlib. No pip install rabbit holes. No supply chain risk. Works on Python 3.8+.

License

Business Source License 1.1. Free for non-production use. Commercial license required for production. Converts to Apache 2.0 on 2036-03-09.