Building Secure, Air-Gapped AI Agents in Python

A complete guide to Skillware 0.5.8: air-gapped media & document authenticity verification, native async execution parity, web form mapping, and open-source supply-chain defense under MIT.

---

When developers build autonomous AI agents today, they quickly encounter a harsh production reality: LLMs are brilliant at high-level reasoning, but catastrophic at deterministic verification.

Ask a state-of-the-art vision model whether an uploaded passport is authentic, and it will give you a convincing narrative—while completely missing that the document number’s modulo-10 cyclic check digit failed, or that the facial photo was spliced using a neural patch. Worse, sending sensitive user IDs or biometric scans to third-party cloud APIs violates GDPR, HIPAA, and basic data sovereignty principles.

Skillware 0.5.8 bridges this gap. It introduces security/deepfake_guard—an air-gapped forensic verification engine that runs entirely in-memory on CPU—alongside native async execution parity, automated web form mapping with anti-CSRF preservation, and an institutional supply-chain defense model called the Permissive Fortress.

Whether you're building an autonomous KYC onboarding pipeline, an enterprise office automation assistant, or a multi-agent DeFi operations bot, here is everything you need to know about what Skillware is, what’s new in 0.5.8, and how to get started in minutes.

---

1. New to Skillware? Here’s How It Works

Skillware is an open-source Python framework providing modular, self-contained, and deterministic capability bundles ("skills") for AI agents.

Instead of letting an LLM hallucinate API calls or execute unvetted code, Skillware provides standardized, pre-packaged skill bundles across Security, Office, DeFi, Compliance, Data Engineering, Optimization, and Creative workflows.

The Four Facets of a Skill Bundle

Every Skillware skill lives under skills/<category>/<skill_name>/ and implements four clear contracts:

1. The Contract (manifest.yaml): Declares strict parameter and output schemas using JSON Schema, environment variables, dependencies, and safety constitutions.
2. The Directive (instructions.md): Explains to the LLM model when, why, and how to use the skill, detailing output semantics and operational edge cases.
3. The Effect (skill.py): Pure Python deterministic logic. No hidden sub-calls, no dynamic eval(), no unpredictable LLM hallucination in the execution path.
4. The Assurance (test_skill.py): Exhaustive Pytest suites verifying parameter validation, boundary conditions, and mock executions before any skill touches production.

Universal Multi-Model Compatibility

Skillware is host-agnostic. A single skill bundle compiles natively into tool/function calling formats for:

• Google Gemini (SkillLoader.to_gemini_tool())
• Anthropic Claude (SkillLoader.to_claude_tool())
• OpenAI & DeepSeek (SkillLoader.to_openai_tool())
• Local Ollama (prompt mode)

You can also execute skills directly in pure Python without an LLM:

from skillware.core.loader import SkillLoader

bundle = SkillLoader.load_skill("security/deepfake_guard")
skill = bundle["class"]()
result = skill.execute({"action": "validate_mrz", "mrz_string": raw_mrz})

---

2. What’s New in Skillware 0.5.8

The 0.5.8 release introduces four foundational upgrades:

🛡️ 1. Air-Gapped Media & Document Guard (security/deepfake_guard)

Running third-party cloud biometric APIs introduces severe privacy risks and operational latency. security/deepfake_guard executes deterministic signal processing, frequency-domain analysis, and mathematical check digit validation strictly in-memory:

• ICAO 9303 Check Digit Validation: Computes cyclic (7, 3, 1) modulo-10 checksums across TD1 (3×30 ID cards), TD2 (2×36), and TD3 (2×44 passports), catching altered expiration dates, forged document numbers, and birth date tampering.
• Error Level Analysis (ELA): Analyzes differential JPEG recompression errors across 16×16 blocks to expose digitally spliced or edited facial regions.
• High-Pass Laplacian Noise Residuals with MAD: Separates authentic camera sensor noise from digital splices using Median Absolute Deviation ($\text{MAD} = \text{median}(|x - \text{median}(x)|)$), avoiding false positives on real high-contrast textures (like hair or knitwear).
• 2D FFT Moiré Recapture Detection: High-frequency 2D Fast Fourier Transform peak ratio analysis catches physical screen-photo recapture (e.g. someone using a smartphone to photograph an ID displayed on a monitor).
• C2PA & Provenance: Detects C2PA JUMBF manifests, Adobe Content Credentials, and generative AI tool tags (trainedAlgorithmicMedia, Midjourney, DALL-E, Stable Diffusion).
• ISO 7810 ID-1 Geometry: Validates standard ID card aspect ratio conformity (~1.586 ± 5%).
• Flexible Entry Points: Accepts file paths (image_path), base64 payloads (image_base64), SSRF-guarded URLs (url), or raw MRZ text (mrz_string).

🏰 2. The Permissive Fortress Architecture

As open-source AI agent tooling proliferates, supply-chain poisoning and rogue code execution are paramount concerns. Skillware 0.5.8 hardens its trust model under the MIT License:

• Inbound Legal & Patent Protection: Strict IP ownership and non-assertion terms in CONTRIBUTING.md, accompanied by mandatory PR template verification.
• Pluggable Credential Sandboxing: Skills now support custom credential_fn callables via BaseSkill.credential(key), allowing host applications to inject secrets per tenant without polluting global os.environ.
• AST Security Audits: Automated CI pipelines (bandit -lll, pip-audit, ruff, mypy) paired with tests/test_security_audit.py banning dynamic execution primitives (eval, exec, compile) across all registry skills.

📝 3. Universal Web Form Mapping (office/web_form_mapper)

Autonomous agents frequently need to submit data to web portals, but fragile browser scraping breaks on dynamic tokens. office/web_form_mapper solves this:

• Discovers form structures, input fields, and selectors automatically.
• Maps fields to central address book legal_profile records.
• Preserves hidden input tokens, anti-CSRF protections, and ASP.NET __VIEWSTATE invariants.
• Detects anti-bot challenges (Cloudflare Turnstile, reCAPTCHA, hCaptcha) and halts fail-closed with status: "needs_input".

⚡ 4. Native Asynchronous Execution Parity

Multi-agent event loops require high-concurrency non-blocking I/O. Skillware 0.5.8 brings full async parity:

• BaseSkill.aexecute(): Asynchronous skill invocation across all skills with automatic non-blocking threadpool offloading.
• SkillContext.aexecute(): Multi-skill context execution with semaphore-backed concurrency throttling via SkillContext(max_concurrency=N).
• skillware.chains.arun_chain(): Asynchronous orchestration for multi-step skill pipelines with conditional branching and timeouts.

---

3. Hands-On Code Walkthroughs: What’s Possible Now

Recipe 1: Air-Gapped Passport & MRZ Validation

Verify an identity document cryptographically without leaking PII to an external cloud endpoint:

from skillware.core.loader import SkillLoader

# Load the deepfake guard bundle
bundle = SkillLoader.load_skill("security/deepfake_guard")
skill = bundle["class"]()

# Validate a passport MRZ payload
result = skill.execute(
    {
        "action": "validate_mrz",
        "mrz_string": (
            "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\n"
            "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
        ),
        "expected_document_type": "passport",
    }
)

print(f"Verdict:   {result['verdict']}")     # "authentic_likely"
print(f"MRZ Valid: {result['mrz_valid']}")   # True
print(f"Summary:   {result['summary']}")     # "ICAO 9303 MRZ checksums valid for UTO P."

If a fraudster altered the expiration date by a single digit, the cyclic modulo-10 algorithm immediately catches the forgery:

# Tampered expiration date from 120415 -> 250415
result_tampered = skill.execute({
    "action": "validate_mrz",
    "mrz_string": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F2504159ZE184226B<<<<<10",
    ],
})

print(result_tampered["verdict"])           # "tampered_likely"
print(result_tampered["checksum_failures"]) # ['expiry_date_checksum', 'composite_checksum']

---

Recipe 2: High-Throughput Async Concurrency

Process hundreds of verification checks concurrently while enforcing resource limits:

import asyncio
from skillware import SkillContext

async def audit_batch(mrz_list):
    # Throttle concurrency to 4 simultaneous workers
    ctx = SkillContext(
        skills=["security/deepfake_guard"],
        max_concurrency=4,
    )

    tasks = [
        ctx.aexecute(
            "security/deepfake_guard",
            {"action": "validate_mrz", "mrz_string": mrz},
            timeout=5.0,
        )
        for mrz in mrz_list
    ]

    results = await asyncio.gather(*tasks)
    clean = sum(1 for r in results if r["verdict"] == "authentic_likely")
    print(f"Batch audit completed: {clean}/{len(results)} assets authentic.")

# Run in an async event loop
# asyncio.run(audit_batch(my_mrz_list))

---

Recipe 3: Pre-Flight KYC & Form Intake Chain

Chain multiple skills using SkillContext to create a secure onboarding funnel:

1. security/deepfake_guard checks image forensics and passport checksums.
2. If tampered or synthetic, halt immediately.
3. If authentic, mask PII with compliance/pii_masker.
4. Map verified data to an onboarding form via office/web_form_mapper.

from skillware import SkillContext

ctx = SkillContext(skills=[
    "security/deepfake_guard",
    "compliance/pii_masker",
    "office/web_form_mapper",
])

# Step 1: Pre-flight forensic audit
auth = ctx.execute("security/deepfake_guard", {
    "action": "inspect_document",
    "image_path": "uploads/applicant_id.jpg",
    "mrz_string": raw_mrz_string,
    "expected_document_type": "passport",
})

if auth["verdict"] in ("tampered_likely", "synthetic_likely", "suspicious"):
    raise PermissionError(f"KYC Verification Failed: {auth['summary']}")

# Step 2: Mask sensitive data before logging
masked = ctx.execute("compliance/pii_masker", {
    "text": f"Applicant {auth['doc']['fields']['surname']} verified."
})
print("Audit Log:", masked["masked_text"])

---

4. What Is Possible in General with Skillware?

Skillware isn't just for KYC—it's an entire ecosystem of modular skills:

Category	Skills & Capabilities
Security	security/deepfake_guard (media & document forensics), security/prompt_injection_firewall (Layer-1 prompt defense & evasion deobfuscation), security/deceptive_ui_guard (dark pattern & malicious web detection).
DeFi / Web3	defi/evm_reader (read-only ERC-20/721 state & multicall queries), defi/token_security_scanner (honeypot/tax pre-trade audit), defi/evm_tx_handler (safe swaps & transfers).
Office	office/gmail_handler (email resolution & dispatch gates), office/pdf_form_filler (AcroForm inspection & filling), office/web_form_mapper (browser-free form discovery & submit).
Compliance	compliance/pii_masker (zero-leakage redaction), compliance/mica_module (EU MiCA crypto asset evaluation), compliance/tos_evaluator (contract policy checks).
Monitoring & Optimization	monitoring/token_limiter (sliding-window budget gates), monitoring/kpi_gate (agent metric tracking), optimization/context_optimizer (semantic compression).

---

5. How to Get Started in 5 Minutes

Step 1: Install Skillware

pip install -U skillware

To install with deepfake forensic extras:

pip install "skillware[security_deepfake_guard]"

Step 2: Run Your First Agent Script

Create agent.py:

import os
import google.genai as genai
from google.genai import types
from skillware.core.loader import SkillLoader

# 1. Load skill bundle
bundle = SkillLoader.load_skill("security/deepfake_guard")
skill = bundle["class"]()
tool = SkillLoader.to_gemini_tool(bundle)

# 2. Bind tool to Gemini
client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Verify this passport MRZ for authenticity: P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\nL898902C36UTO7408122F1204159ZE184226B<<<<<10",
    config=types.GenerateContentConfig(
        tools=[tool],
        system_instruction=bundle["instructions"],
    ),
)

# 3. Execute tool call deterministically
for part in response.candidates[0].content.parts:
    if part.function_call:
        result = skill.execute(dict(part.function_call.args))
        print("Verdict:", result["verdict"])
        print("Summary:", result["summary"])

Step 3: Explore the CLI

Skillware ships with an interactive command-line interface:

# Check system health and install integrity
skillware doctor

# List all available skills across all categories
skillware list

# Inspect configuration and active merges
skillware config show

---

6. How to Get Involved

Skillware is 100% open source under the MIT License and maintained by ARPA Hellenic Logical Systems.

We actively welcome contributors! Here is how you can jump in:

• ⭐ Star the repo: github.com/ARPAHLS/skillware
• 🐛 Pick a Good First Issue: Browse our curated good first issues.
• 🛠️ Create a New Skill: Use our modern starter template:

  cp -r templates/python_skill skills/<category>/<your_skill>

• 📖 Read the Docs: Check out skillware.site for full API references, architecture guides, and tutorials.

Give Skillware 0.5.8 a spin today and build AI agents that are truly robust, secure, and production-ready!