sigui-security

name	sigui-security
version	2.0.1
description	AI security oracle for blockchain transactions. Evaluates EVM, Starknet, and Aptos transactions in real time using the Sigui Protocol — detecting drain stars, mixer chains, Sybil swarms, and flash-loan exploits before execution. Returns ALLOW / BLOCK / ESCALATE with an on-chain proof. Requires a real Sigui API endpoint; demo mode available for testing.
author	Warma Abdoul Ibonon Eric <[e-mail]>
homepage	https://github.com/ibonon/Sigui
license	MIT
tags	["blockchain","security","web3","defi","ai-agent","ethereum","starknet","aptos"]
read_when	["The user explicitly asks to evaluate, audit, or check the safety of a specific blockchain transaction before sending it","The user says \"check this address\", \"is this contract safe\", or \"evaluate this transaction\" and provides concrete parameters (address, amount, chain)","The user reports a suspected rug pull, drain attack, phishing approval, or flash-loan exploit they want analyzed","An autonomous agent is about to submit an on-chain transaction and needs security clearance"]
install	{"run":"bash install.sh"}
requires	{"python":">=3.10","packages":["sigui-sdk>=0.3.1","rich>=13.0.0"]}

Sigui Protocol Security Skill 🛡️

Sigui is a multi-chain AI security oracle that evaluates blockchain transactions before they execute, using a native Spatio-Temporal Transformer (Trustformer/T-GAT) to detect coordinated attacks in real time.

[!IMPORTANT] This skill requires a real Sigui API endpoint for production use. Set SIGUI_API_URL to your node URL. Without it, the script exits safely (fail-closed). A --demo flag is available for testing, but MUST NOT be used to authorize real funds.

---

🔐 Security Model

This skill is designed with a fail-closed security policy:

Situation	Behavior
No API URL configured	❌ Exits with error — does NOT simulate
API unreachable	❌ Exits with error — does NOT simulate
ALLOW verdict	⏸️ Pauses and asks for explicit user confirmation
BLOCK verdict	🚫 Immediately returns exit code 1
ESCALATE verdict	🔍 Requests deep analysis with --escalate
--demo flag set	⚠️ Shows prominent warning — heuristic only

---

🧠 Agent Instructions (Chain of Thought)

When a user explicitly asks to evaluate a specific transaction, follow these steps:

Step 1 — Extract Parameters

Identify from the user's message:

• amount: transaction value (convert to USDC equivalent if needed)
• destination: the target wallet or contract address
• chain: the blockchain (default arc)
• action: the action type (transfer, approve, swap, bridge, mint)

If any required parameter is missing, ask the user before running the evaluation.

Step 2 — Ask for Explicit Confirmation Before Running

Before executing the script, show the user:

"I'm about to evaluate this transaction with the Sigui security oracle:

• Amount: {amount} USDC
• Destination: {destination}
• Chain: {chain}
• Action: {action} Shall I proceed?"

Step 3 — Run the Evaluation

python ~/.openclaw/workspace/skills/sigui-security/evaluate.py \
  --amount {amount} \
  --destination {destination} \
  --action {action} \
  --chain {chain}

Step 4 — Interpret the Exit Code

Exit Code	Verdict	Agent Action
0	ALLOW	Ask user: "Sigui approves. Do you confirm the transaction?" Only proceed if user says yes.
1	BLOCK	🚫 ABORT. Tell the user the threat detected. Do NOT proceed.
2	ESCALATE	Ask user if they want deep analysis, then re-run with --escalate.
3	Error	Report the error. Do NOT proceed with the transaction.

Step 5 — After ALLOW: Require User Confirmation

Re-run with --confirmed only after the user explicitly says yes:

python evaluate.py --amount {amount} --destination {destination} \
  --action {action} --chain {chain} --confirmed

---

🛠️ Setup

1. Install Dependencies (automatic)

The skill auto-installs sigui-sdk when first run. Or run manually:

bash ~/.openclaw/workspace/skills/sigui-security/install.sh

2. Configure Your Sigui Endpoint (required for production)

export SIGUI_API_URL="https://your-sigui-node.com"
export SIGUI_CHAIN="arc"           # Optional, default: arc
export OPENCLAW_AGENT_ID="my_agent"  # Optional

3. Test in Demo Mode (non-authoritative)

python evaluate.py --amount 50 --destination 0xYourAddress --demo

⚠️ Demo mode output is a local heuristic simulation, NOT an oracle evaluation. Never use demo results to authorize transactions.

---

📊 Verdict Table

Verdict	Risk Score	Meaning
ALLOW	0.0–0.35	Transaction appears safe — await user confirmation
ALLOW_WITH_CAP	0.35–0.55	Safe up to spending cap — await user confirmation
ESCALATE	0.55–0.80	Ambiguous — request deep analysis before deciding
BLOCK	0.80–1.0	Threat detected — do NOT proceed

Safety Score = (1 - risk_score) × 1000. Higher = safer.

---

🛡️ Threats Detected

Attack	Description
Drain Star	Orchestrator draining multiple wallets simultaneously
Mixing Chain	Layered hops through mixers to obscure fund origin
Sybil Swarm	Fake-identity cluster attacking governance or airdrops
Flash Loan Exploit	Oracle price manipulation within one atomic block
Honeypot Contract	Buy-enabled, sell-disabled token trap
Rug Pull	Liquidity removal by deployer
Phishing Signature	Malicious eth_sign / permit approval

---

🔗 Links

• 📄 GitHub: https://github.com/ibonon/Sigui
• 📦 PyPI: https://pypi.org/project/sigui-sdk/
• 🌐 ClawHub: https://clawhub.ai/ibonon/sigui-security
• 📖 Whitepaper: Sigui Protocol: A Real-Time Security Oracle for Autonomous AI Agents