agentx-security-sdk 0.2.1__tar.gz → 0.2.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/PKG-INFO +78 -65
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_sdk/decorators.py +60 -26
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/PKG-INFO +78 -65
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/setup.py +1 -1
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/README.txt +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_sdk/__init__.py +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_sdk/client.py +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_sdk/db.py +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/SOURCES.txt +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/dependency_links.txt +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/requires.txt +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/top_level.txt +0 -0
- {agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agentx-security-sdk
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: The self-healing exception handler for autonomous AI agents.
|
|
5
5
|
Home-page: https://github.com/vdalal/semantic-gateway
|
|
6
6
|
Author: AgentX Team
|
|
@@ -23,29 +23,83 @@ Dynamic: requires-dist
|
|
|
23
23
|
Dynamic: requires-python
|
|
24
24
|
Dynamic: summary
|
|
25
25
|
|
|
26
|
-
# AgentX
|
|
26
|
+
# 🛡️ AgentX: The Semantic Firewall for AI Agents
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
[](https://www.python.org/downloads/)
|
|
29
|
+
[](https://opensource.org/licenses/MIT)
|
|
29
30
|
|
|
30
|
-
|
|
31
|
+
LLM Agents are brilliant, but they are incredibly brittle. They will drop your production database, leak AWS keys, and fall victim to prompt injections. Traditional firewalls just crash the agent by returning a `403 Forbidden`.
|
|
31
32
|
|
|
32
|
-
|
|
33
|
+
**AgentX is different.** It is a neuro-symbolic edge gateway that intercepts dangerous tool calls, blocks them, and returns a **Socratic Challenge** back to the agent's context window—forcing the agent to rethink its strategy and self-correct *without crashing*.
|
|
34
|
+
|
|
35
|
+
### 🧠 Don't just block agents. Coach them.
|
|
36
|
+
```text
|
|
37
|
+
════════════════════════════════════════════════════════════
|
|
38
|
+
🛡️ AgentX Session Summary (Trace: 7012938b-4cde-4bea-aac8)
|
|
39
|
+
════════════════════════════════════════════════════════════
|
|
40
|
+
⏱️ Uptime: 15.49 seconds
|
|
41
|
+
🛠️ Tools Monitored: 2
|
|
42
|
+
────────────────────────────────────────────────────────────
|
|
43
|
+
🛑 Intercepts: 1 | Cumulative: 34
|
|
44
|
+
💥 Critical Blocks: 1 | Cumulative: 18
|
|
45
|
+
🔄 Self-Corrections: 1 | Recovery Rate: 100.0%
|
|
46
|
+
💰 Tokens Saved: ~1500 | Cumulative: ~51000
|
|
47
|
+
⏳ Time Saved: ~5s | Cumulative: ~170s
|
|
48
|
+
════════════════════════════════════════════════════════════
|
|
49
|
+
🩺 AGENT HEALTH INSIGHT
|
|
50
|
+
────────────────────────────────────────────────────────────
|
|
51
|
+
⚠️ Top Offender: 'Database Isolation'
|
|
52
|
+
💡 Tip: Consider refining your agent's system prompt to avoid this.
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
🚀 The 4 Shields (Defense-in-Depth)
|
|
56
|
+
The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.
|
|
57
|
+
|
|
58
|
+
The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.
|
|
59
|
+
|
|
60
|
+
The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).
|
|
61
|
+
|
|
62
|
+
The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
⚡ Quickstart (Time-to-Value < 3 Minutes)
|
|
66
|
+
1. Install the SDK
|
|
67
|
+
Zero-config integration for your Python agents.
|
|
33
68
|
|
|
34
|
-
Install the SDK via PyPI:
|
|
35
69
|
```bash
|
|
36
70
|
pip install agentx-security-sdk
|
|
37
71
|
```
|
|
38
|
-
|
|
39
|
-
|
|
72
|
+
2. Wrap your Tools
|
|
73
|
+
Add the @agentx_protect decorator to any function your LangChain, AutoGen, or custom ReAct agent uses. AgentX operates out-of-band, adding zero latency to safe calls.
|
|
40
74
|
|
|
41
75
|
```python
|
|
42
76
|
from agentx_sdk.decorators import agentx_protect
|
|
43
77
|
|
|
44
|
-
@agentx_protect(agent_id="
|
|
78
|
+
@agentx_protect(agent_id="customer_support_agent")
|
|
45
79
|
def execute_database_query(query: str):
|
|
46
|
-
# Your
|
|
80
|
+
# Your local logic here
|
|
47
81
|
return db.execute(query)
|
|
82
|
+
```
|
|
83
|
+
3. Spin up the Edge Gateway
|
|
84
|
+
AgentX requires an Edge node to process heuristics and embeddings at sub-millisecond speeds.
|
|
85
|
+
|
|
86
|
+
Clone this repository.
|
|
87
|
+
|
|
88
|
+
Copy .env.example to .env and add your API keys (SUPABASE_URL, SUPABASE_KEY, GEMINI_API_KEY).
|
|
89
|
+
|
|
90
|
+
Boot the gateway:
|
|
48
91
|
|
|
92
|
+
```bash
|
|
93
|
+
docker-compose up -d
|
|
94
|
+
```
|
|
95
|
+
The gateway is now listening on http://localhost:8000 and mirroring policies from your Control Plane.
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
4. Run the Simulation
|
|
99
|
+
Watch the AgentX Gateway coach a rogue agent in real-time.
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
python examples/simulate_agent_sdk.py
|
|
49
103
|
```
|
|
50
104
|
|
|
51
105
|
## 📊 Local Telemetry & Agent Health
|
|
@@ -72,6 +126,20 @@ AgentX ships with a built-in, privacy-first SQLite time-series event log (`.agen
|
|
|
72
126
|
|
|
73
127
|
```
|
|
74
128
|
|
|
129
|
+
## 🕹️ Human-in-the-Loop (HITL) & Control Plane
|
|
130
|
+
Sometimes, an agent needs to drop a table for a valid business reason.
|
|
131
|
+
|
|
132
|
+
AgentX features a Next.js Control Plane Dashboard. If an agent requests an escalation, the SDK securely pauses local execution and polls the Edge Gateway. A human SOC analyst can click "Approve" or "Deny" in the UI, and the Python execution loop will automatically resume.
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
cd ui
|
|
136
|
+
npm install
|
|
137
|
+
npm run dev
|
|
138
|
+
|
|
139
|
+
## 🤝 Contributing
|
|
140
|
+
We are actively looking for design partners. If you are building autonomous agents in production and are terrified of what they might do, open an issue or reach out!
|
|
141
|
+
|
|
142
|
+
|
|
75
143
|
## 🏗️ The Architecture (Split-Plane)
|
|
76
144
|
|
|
77
145
|
AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.
|
|
@@ -89,61 +157,6 @@ AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum perfor
|
|
|
89
157
|
* **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
|
|
90
158
|
* **Dynamic YAML Policies:** Enforces isolation rules like "Mass Destructive Intent", "Database Isolation", "Network Sandbox (SSRF)", and "Secrets Exfiltration".
|
|
91
159
|
|
|
92
|
-
## 🛠️ Getting Started (Backend Deployment)
|
|
93
|
-
|
|
94
|
-
If you are deploying your own instance of the Semantic Gateway Control Plane:
|
|
95
|
-
|
|
96
|
-
### Prerequisites
|
|
97
|
-
|
|
98
|
-
* Python 3.10+
|
|
99
|
-
* Node.js 18+
|
|
100
|
-
* [Supabase](https://supabase.com) Account
|
|
101
|
-
* [Google AI Studio](https://aistudio.google.com/) API Key (Gemini)
|
|
102
|
-
|
|
103
|
-
### 1. Environment Variables
|
|
104
|
-
|
|
105
|
-
Create a `.env` file in the root directory. **Ensure this file is in your `.gitignore` to protect your IP and keys.**
|
|
106
|
-
|
|
107
|
-
```env
|
|
108
|
-
SUPABASE_URL=your_supabase_url
|
|
109
|
-
SUPABASE_KEY=your_supabase_service_role_key
|
|
110
|
-
GEMINI_API_KEY=your_gemini_api_key
|
|
111
|
-
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### 2. Run the Semantic Firewall (Dockerized)
|
|
115
|
-
The Data Plane (Wedge) is fully containerized for maximum reliability. Make sure your `.env` is configured in the root directory, then build and run the backend:
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
cd backend
|
|
119
|
-
docker build -t agentx-gateway .
|
|
120
|
-
docker run -p 8000:8000 --env-file ../.env agentx-gateway
|
|
121
|
-
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
The firewall is now intercepting traffic at http://localhost:8000
|
|
125
|
-
|
|
126
|
-
### 3. Run the Control Plane Dashboard (Vercel/Local)
|
|
127
|
-
|
|
128
|
-
Start your Next.js application to view the intercepted incidents.
|
|
129
|
-
|
|
130
|
-
```bash
|
|
131
|
-
cd ui
|
|
132
|
-
npm install
|
|
133
|
-
npm run dev
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
Your dashboard is now live at http://localhost:3000
|
|
137
|
-
|
|
138
|
-
### 4. Run the Agent Simulation
|
|
139
|
-
|
|
140
|
-
Simulate a rogue agent attempting a destructive action. Watch the firewall intercept it, issue a challenge, and route it to your dashboard.
|
|
141
|
-
|
|
142
|
-
```bash
|
|
143
|
-
python examples/simulate_agent_sdk.py
|
|
144
|
-
|
|
145
|
-
```
|
|
146
|
-
|
|
147
160
|
## 🔒 Security Posture
|
|
148
161
|
|
|
149
162
|
* **Secret Management:** API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
|
|
@@ -24,23 +24,39 @@ def start_secure_session():
|
|
|
24
24
|
trace_id_var.set(session_id)
|
|
25
25
|
return session_id
|
|
26
26
|
|
|
27
|
-
# --- 1. THE SESSION TRACKER ---
|
|
27
|
+
# --- 1. THE SESSION TRACKER & EXIT SUMMARY ---
|
|
28
28
|
_session_stats = {
|
|
29
29
|
"start_time": time.time(),
|
|
30
30
|
"total_calls": 0,
|
|
31
31
|
"intercepts": 0,
|
|
32
|
-
"critical_blocks": 0
|
|
32
|
+
"critical_blocks": 0,
|
|
33
|
+
"self_corrections": 0,
|
|
34
|
+
"last_call_was_challenge": False # <-- Tracks the cognitive pivot state
|
|
33
35
|
}
|
|
34
36
|
|
|
35
|
-
def
|
|
37
|
+
def _print_agentx_summary():
|
|
36
38
|
"""Fires automatically when the developer's script ends or crashes."""
|
|
39
|
+
|
|
40
|
+
# Only print if we actually did something this session to avoid terminal spam
|
|
41
|
+
if _session_stats["total_calls"] == 0 and _session_stats["intercepts"] == 0:
|
|
42
|
+
return
|
|
43
|
+
|
|
37
44
|
duration = round(time.time() - _session_stats["start_time"], 2)
|
|
38
45
|
session_tokens = _session_stats["intercepts"] * 1500
|
|
39
46
|
session_time = _session_stats["intercepts"] * 5
|
|
40
47
|
|
|
48
|
+
# Calculate the Hero Metric: Self-Correction Rate
|
|
49
|
+
scr = 0
|
|
50
|
+
if _session_stats["intercepts"] > 0:
|
|
51
|
+
scr = round((_session_stats["self_corrections"] / _session_stats["intercepts"]) * 100, 1)
|
|
52
|
+
|
|
41
53
|
# Fetch historical data
|
|
42
|
-
|
|
43
|
-
|
|
54
|
+
try:
|
|
55
|
+
history = get_lifetime_stats()
|
|
56
|
+
if not history:
|
|
57
|
+
raise ValueError("No history")
|
|
58
|
+
except Exception:
|
|
59
|
+
# Fallback if the local DB is fresh or errors out
|
|
44
60
|
history = {
|
|
45
61
|
"total_intercepts": _session_stats["intercepts"],
|
|
46
62
|
"total_critical": _session_stats["critical_blocks"],
|
|
@@ -49,30 +65,31 @@ def _print_roi_summary():
|
|
|
49
65
|
"top_offender": None
|
|
50
66
|
}
|
|
51
67
|
|
|
52
|
-
print("\n" + "═"*
|
|
68
|
+
print("\n" + "═"*60)
|
|
53
69
|
print(f" 🛡️ AgentX Session Summary (Trace: {trace_id_var.get() or 'N/A'})")
|
|
54
|
-
print("═"*
|
|
70
|
+
print("═"*60)
|
|
55
71
|
print(f" ⏱️ Uptime: {duration} seconds")
|
|
56
72
|
print(f" 🛠️ Tools Monitored: {_session_stats['total_calls']}")
|
|
57
|
-
print("─"*
|
|
73
|
+
print("─"*60)
|
|
58
74
|
|
|
59
75
|
# The Action-Oriented UI
|
|
60
76
|
print(f" 🛑 Intercepts: {_session_stats['intercepts']} | Cumulative: {history['total_intercepts']}")
|
|
61
77
|
print(f" 💥 Critical Blocks: {_session_stats['critical_blocks']} | Cumulative: {history['total_critical']}")
|
|
62
|
-
print(f"
|
|
63
|
-
print(f"
|
|
78
|
+
print(f" 🔄 Self-Corrections: {_session_stats['self_corrections']} | Recovery Rate: {scr}%")
|
|
79
|
+
print(f" 💰 Tokens Saved: ~{session_tokens} | Cumulative: ~{history['total_tokens']}")
|
|
80
|
+
print(f" ⏳ Time Saved: ~{session_time}s | Cumulative: ~{history['total_time']}s")
|
|
64
81
|
|
|
65
82
|
# The 5+ Block Threshold for the Health Report
|
|
66
|
-
if history
|
|
67
|
-
print("═"*
|
|
83
|
+
if history.get('total_intercepts', 0) >= 5 and history.get('top_offender'):
|
|
84
|
+
print("═"*60)
|
|
68
85
|
print(" 🩺 AGENT HEALTH INSIGHT")
|
|
69
|
-
print("─"*
|
|
70
|
-
print(f" ⚠️
|
|
71
|
-
print("
|
|
86
|
+
print("─"*60)
|
|
87
|
+
print(f" ⚠️ Top Offender: '{history['top_offender']}'")
|
|
88
|
+
print(" 💡 Tip: Consider refining your agent's system prompt to avoid this.")
|
|
72
89
|
|
|
73
|
-
print("═"*
|
|
90
|
+
print("═"*60 + "\n")
|
|
74
91
|
|
|
75
|
-
atexit.register(
|
|
92
|
+
atexit.register(_print_agentx_summary)
|
|
76
93
|
# --------------------------
|
|
77
94
|
|
|
78
95
|
def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None):
|
|
@@ -101,6 +118,9 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
101
118
|
_session_stats["intercepts"] += 1
|
|
102
119
|
_session_stats["critical_blocks"] += 1
|
|
103
120
|
|
|
121
|
+
# +++ SENSOR: Track that we challenged the agent
|
|
122
|
+
_session_stats["last_call_was_challenge"] = True
|
|
123
|
+
|
|
104
124
|
mock_policy_id = "POL-SEC-001"
|
|
105
125
|
mock_policy_name = "Database Isolation"
|
|
106
126
|
|
|
@@ -115,6 +135,12 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
115
135
|
})
|
|
116
136
|
else:
|
|
117
137
|
print(f"✅ [AgentX SDK] Intent safe (Mock). Executing '{func.__name__}'.")
|
|
138
|
+
|
|
139
|
+
# +++ SENSOR: Check if this was a successful recovery!
|
|
140
|
+
if _session_stats.get("last_call_was_challenge"):
|
|
141
|
+
_session_stats["self_corrections"] += 1
|
|
142
|
+
_session_stats["last_call_was_challenge"] = False
|
|
143
|
+
|
|
118
144
|
return func(*args, **kwargs)
|
|
119
145
|
|
|
120
146
|
# =========================================================
|
|
@@ -125,7 +151,7 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
125
151
|
query=query,
|
|
126
152
|
chain_of_thought=chain_of_thought,
|
|
127
153
|
receipt_id=receipt_id,
|
|
128
|
-
trace_id=current_trace_id
|
|
154
|
+
trace_id=current_trace_id
|
|
129
155
|
)
|
|
130
156
|
|
|
131
157
|
status = eval_res.get("status") if isinstance(eval_res, dict) else None
|
|
@@ -134,6 +160,9 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
134
160
|
if isinstance(eval_res, dict) and eval_res.get("error") == "AgentX Policy Violation":
|
|
135
161
|
_session_stats["intercepts"] += 1
|
|
136
162
|
|
|
163
|
+
# +++ SENSOR: Track that we challenged the agent
|
|
164
|
+
_session_stats["last_call_was_challenge"] = True
|
|
165
|
+
|
|
137
166
|
actual_policy_id = eval_res.get("policy_id", "POL-UNKNOWN")
|
|
138
167
|
policy_name = eval_res.get("policy_triggered", "Unknown Policy")
|
|
139
168
|
challenge_text = eval_res.get("challenge", "Policy violation detected. Please revise your intent.")
|
|
@@ -166,15 +195,13 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
166
195
|
print(f"\n🚨 [AgentX SDK] Task suspended. Request escalated to Human SOC.")
|
|
167
196
|
print(f"⏳ [AgentX SDK] Polling for human decision (Receipt: {receipt_id})...")
|
|
168
197
|
|
|
169
|
-
# Retrieve the API key for the polling requests
|
|
170
198
|
api_key = os.environ.get("AGENTX_API_KEY")
|
|
171
199
|
headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
|
|
172
200
|
|
|
173
201
|
# The Polling Loop
|
|
174
202
|
while True:
|
|
175
|
-
time.sleep(3)
|
|
203
|
+
time.sleep(3)
|
|
176
204
|
try:
|
|
177
|
-
# Check the status endpoint with Auth Headers
|
|
178
205
|
status_check = requests.get(
|
|
179
206
|
f"{_client.gateway_url}/v1/status/{receipt_id}",
|
|
180
207
|
headers=headers
|
|
@@ -184,7 +211,8 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
184
211
|
|
|
185
212
|
if current_status == "APPROVED":
|
|
186
213
|
print(f"\n✅ [AgentX SDK] Human SOC APPROVED the override!")
|
|
187
|
-
#
|
|
214
|
+
# Reset state, this wasn't a self-correction, human bypassed it.
|
|
215
|
+
_session_stats["last_call_was_challenge"] = False
|
|
188
216
|
return func(*args, **kwargs)
|
|
189
217
|
|
|
190
218
|
elif current_status == "DENIED":
|
|
@@ -194,18 +222,24 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
|
|
|
194
222
|
"instruction": "The SOC analyst explicitly denied this action. You must find an alternative path or fail the task."
|
|
195
223
|
})
|
|
196
224
|
|
|
197
|
-
# If PENDING or ESCALATED, it just loops again
|
|
198
225
|
elif status_check.status_code == 401:
|
|
199
|
-
print(f"\n❌ [AgentX SDK] Auth Error: Gateway rejected polling request.
|
|
226
|
+
print(f"\n❌ [AgentX SDK] Auth Error: Gateway rejected polling request.")
|
|
200
227
|
return json.dumps({"error": "Unauthorized Polling"})
|
|
201
228
|
|
|
202
229
|
except Exception as e:
|
|
203
230
|
print(f"⚠️ Polling error: {e}")
|
|
204
231
|
|
|
205
232
|
# 3. Check for the "Success" path
|
|
206
|
-
elif isinstance(eval_res, dict) and eval_res.get("status")
|
|
233
|
+
elif isinstance(eval_res, dict) and eval_res.get("status") in ["success", "ALLOWED"]:
|
|
207
234
|
print(f"✅ [AgentX SDK] Intent safe. Executing '{func.__name__}'.")
|
|
208
|
-
|
|
235
|
+
|
|
236
|
+
# +++ SENSOR: Check if this was a successful recovery!
|
|
237
|
+
if _session_stats.get("last_call_was_challenge"):
|
|
238
|
+
_session_stats["self_corrections"] += 1
|
|
239
|
+
_session_stats["last_call_was_challenge"] = False
|
|
240
|
+
|
|
241
|
+
# Fix: Actually execute the function instead of returning the Gateway's JSON
|
|
242
|
+
return func(*args, **kwargs)
|
|
209
243
|
|
|
210
244
|
# 4. Handle actual Gateway crashes
|
|
211
245
|
else:
|
{agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agentx-security-sdk
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: The self-healing exception handler for autonomous AI agents.
|
|
5
5
|
Home-page: https://github.com/vdalal/semantic-gateway
|
|
6
6
|
Author: AgentX Team
|
|
@@ -23,29 +23,83 @@ Dynamic: requires-dist
|
|
|
23
23
|
Dynamic: requires-python
|
|
24
24
|
Dynamic: summary
|
|
25
25
|
|
|
26
|
-
# AgentX
|
|
26
|
+
# 🛡️ AgentX: The Semantic Firewall for AI Agents
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
[](https://www.python.org/downloads/)
|
|
29
|
+
[](https://opensource.org/licenses/MIT)
|
|
29
30
|
|
|
30
|
-
|
|
31
|
+
LLM Agents are brilliant, but they are incredibly brittle. They will drop your production database, leak AWS keys, and fall victim to prompt injections. Traditional firewalls just crash the agent by returning a `403 Forbidden`.
|
|
31
32
|
|
|
32
|
-
|
|
33
|
+
**AgentX is different.** It is a neuro-symbolic edge gateway that intercepts dangerous tool calls, blocks them, and returns a **Socratic Challenge** back to the agent's context window—forcing the agent to rethink its strategy and self-correct *without crashing*.
|
|
34
|
+
|
|
35
|
+
### 🧠 Don't just block agents. Coach them.
|
|
36
|
+
```text
|
|
37
|
+
════════════════════════════════════════════════════════════
|
|
38
|
+
🛡️ AgentX Session Summary (Trace: 7012938b-4cde-4bea-aac8)
|
|
39
|
+
════════════════════════════════════════════════════════════
|
|
40
|
+
⏱️ Uptime: 15.49 seconds
|
|
41
|
+
🛠️ Tools Monitored: 2
|
|
42
|
+
────────────────────────────────────────────────────────────
|
|
43
|
+
🛑 Intercepts: 1 | Cumulative: 34
|
|
44
|
+
💥 Critical Blocks: 1 | Cumulative: 18
|
|
45
|
+
🔄 Self-Corrections: 1 | Recovery Rate: 100.0%
|
|
46
|
+
💰 Tokens Saved: ~1500 | Cumulative: ~51000
|
|
47
|
+
⏳ Time Saved: ~5s | Cumulative: ~170s
|
|
48
|
+
════════════════════════════════════════════════════════════
|
|
49
|
+
🩺 AGENT HEALTH INSIGHT
|
|
50
|
+
────────────────────────────────────────────────────────────
|
|
51
|
+
⚠️ Top Offender: 'Database Isolation'
|
|
52
|
+
💡 Tip: Consider refining your agent's system prompt to avoid this.
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
🚀 The 4 Shields (Defense-in-Depth)
|
|
56
|
+
The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.
|
|
57
|
+
|
|
58
|
+
The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.
|
|
59
|
+
|
|
60
|
+
The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).
|
|
61
|
+
|
|
62
|
+
The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
⚡ Quickstart (Time-to-Value < 3 Minutes)
|
|
66
|
+
1. Install the SDK
|
|
67
|
+
Zero-config integration for your Python agents.
|
|
33
68
|
|
|
34
|
-
Install the SDK via PyPI:
|
|
35
69
|
```bash
|
|
36
70
|
pip install agentx-security-sdk
|
|
37
71
|
```
|
|
38
|
-
|
|
39
|
-
|
|
72
|
+
2. Wrap your Tools
|
|
73
|
+
Add the @agentx_protect decorator to any function your LangChain, AutoGen, or custom ReAct agent uses. AgentX operates out-of-band, adding zero latency to safe calls.
|
|
40
74
|
|
|
41
75
|
```python
|
|
42
76
|
from agentx_sdk.decorators import agentx_protect
|
|
43
77
|
|
|
44
|
-
@agentx_protect(agent_id="
|
|
78
|
+
@agentx_protect(agent_id="customer_support_agent")
|
|
45
79
|
def execute_database_query(query: str):
|
|
46
|
-
# Your
|
|
80
|
+
# Your local logic here
|
|
47
81
|
return db.execute(query)
|
|
82
|
+
```
|
|
83
|
+
3. Spin up the Edge Gateway
|
|
84
|
+
AgentX requires an Edge node to process heuristics and embeddings at sub-millisecond speeds.
|
|
85
|
+
|
|
86
|
+
Clone this repository.
|
|
87
|
+
|
|
88
|
+
Copy .env.example to .env and add your API keys (SUPABASE_URL, SUPABASE_KEY, GEMINI_API_KEY).
|
|
89
|
+
|
|
90
|
+
Boot the gateway:
|
|
48
91
|
|
|
92
|
+
```bash
|
|
93
|
+
docker-compose up -d
|
|
94
|
+
```
|
|
95
|
+
The gateway is now listening on http://localhost:8000 and mirroring policies from your Control Plane.
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
4. Run the Simulation
|
|
99
|
+
Watch the AgentX Gateway coach a rogue agent in real-time.
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
python examples/simulate_agent_sdk.py
|
|
49
103
|
```
|
|
50
104
|
|
|
51
105
|
## 📊 Local Telemetry & Agent Health
|
|
@@ -72,6 +126,20 @@ AgentX ships with a built-in, privacy-first SQLite time-series event log (`.agen
|
|
|
72
126
|
|
|
73
127
|
```
|
|
74
128
|
|
|
129
|
+
## 🕹️ Human-in-the-Loop (HITL) & Control Plane
|
|
130
|
+
Sometimes, an agent needs to drop a table for a valid business reason.
|
|
131
|
+
|
|
132
|
+
AgentX features a Next.js Control Plane Dashboard. If an agent requests an escalation, the SDK securely pauses local execution and polls the Edge Gateway. A human SOC analyst can click "Approve" or "Deny" in the UI, and the Python execution loop will automatically resume.
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
cd ui
|
|
136
|
+
npm install
|
|
137
|
+
npm run dev
|
|
138
|
+
|
|
139
|
+
## 🤝 Contributing
|
|
140
|
+
We are actively looking for design partners. If you are building autonomous agents in production and are terrified of what they might do, open an issue or reach out!
|
|
141
|
+
|
|
142
|
+
|
|
75
143
|
## 🏗️ The Architecture (Split-Plane)
|
|
76
144
|
|
|
77
145
|
AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.
|
|
@@ -89,61 +157,6 @@ AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum perfor
|
|
|
89
157
|
* **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
|
|
90
158
|
* **Dynamic YAML Policies:** Enforces isolation rules like "Mass Destructive Intent", "Database Isolation", "Network Sandbox (SSRF)", and "Secrets Exfiltration".
|
|
91
159
|
|
|
92
|
-
## 🛠️ Getting Started (Backend Deployment)
|
|
93
|
-
|
|
94
|
-
If you are deploying your own instance of the Semantic Gateway Control Plane:
|
|
95
|
-
|
|
96
|
-
### Prerequisites
|
|
97
|
-
|
|
98
|
-
* Python 3.10+
|
|
99
|
-
* Node.js 18+
|
|
100
|
-
* [Supabase](https://supabase.com) Account
|
|
101
|
-
* [Google AI Studio](https://aistudio.google.com/) API Key (Gemini)
|
|
102
|
-
|
|
103
|
-
### 1. Environment Variables
|
|
104
|
-
|
|
105
|
-
Create a `.env` file in the root directory. **Ensure this file is in your `.gitignore` to protect your IP and keys.**
|
|
106
|
-
|
|
107
|
-
```env
|
|
108
|
-
SUPABASE_URL=your_supabase_url
|
|
109
|
-
SUPABASE_KEY=your_supabase_service_role_key
|
|
110
|
-
GEMINI_API_KEY=your_gemini_api_key
|
|
111
|
-
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### 2. Run the Semantic Firewall (Dockerized)
|
|
115
|
-
The Data Plane (Wedge) is fully containerized for maximum reliability. Make sure your `.env` is configured in the root directory, then build and run the backend:
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
cd backend
|
|
119
|
-
docker build -t agentx-gateway .
|
|
120
|
-
docker run -p 8000:8000 --env-file ../.env agentx-gateway
|
|
121
|
-
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
The firewall is now intercepting traffic at http://localhost:8000
|
|
125
|
-
|
|
126
|
-
### 3. Run the Control Plane Dashboard (Vercel/Local)
|
|
127
|
-
|
|
128
|
-
Start your Next.js application to view the intercepted incidents.
|
|
129
|
-
|
|
130
|
-
```bash
|
|
131
|
-
cd ui
|
|
132
|
-
npm install
|
|
133
|
-
npm run dev
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
Your dashboard is now live at http://localhost:3000
|
|
137
|
-
|
|
138
|
-
### 4. Run the Agent Simulation
|
|
139
|
-
|
|
140
|
-
Simulate a rogue agent attempting a destructive action. Watch the firewall intercept it, issue a challenge, and route it to your dashboard.
|
|
141
|
-
|
|
142
|
-
```bash
|
|
143
|
-
python examples/simulate_agent_sdk.py
|
|
144
|
-
|
|
145
|
-
```
|
|
146
|
-
|
|
147
160
|
## 🔒 Security Posture
|
|
148
161
|
|
|
149
162
|
* **Secret Management:** API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/SOURCES.txt
RENAMED
|
File without changes
|
|
File without changes
|
{agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/requires.txt
RENAMED
|
File without changes
|
{agentx_security_sdk-0.2.1 → agentx_security_sdk-0.2.2}/agentx_security_sdk.egg-info/top_level.txt
RENAMED
|
File without changes
|
|
File without changes
|