Getting Started
Quickstart
Install XIPE, configure a target, and run your first assessment in under 3 minutes.
bash# 1. Clone & install
git clone https://github.com/RickDevopsSecure/-XIPE-AI-Security-Scanner
cd -XIPE-AI-Security-Scanner
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# 2. Configure
cp config.yaml.example config.yaml
# Edit config.yaml → set scope.base_urls, engagement.id, credentials
# 3. Run
python main.py --config config.yaml
# 4. With real-time dashboard (port 5001)
python main.py --config config.yaml --dashboard
# 5. Run specific modules only
python main.py --config config.yaml --modules api_mapper,prompt_injection,rag_tester
Output files generated in output/:
| File | Format | Description |
|---|
| findings.json | JSON | All findings with full scoring, evidence, and OWASP mappings |
| report.html | HTML | Interactive report — filterable by severity, module, category |
| report.pdf | PDF | Professional report with cover page, exec summary, and appendices |
| pentest.log | Text | Full engagement log with phase timings and module decisions |
Configuration
config.yaml Reference
Full configuration reference. Copy config.yaml.example — never commit the real file (it's gitignored).
yaml# ── Engagement (required — authorization record) ──────────
engagement:
id: "ENG-2026-001" # Unique ID — appears in PDF
client_name: "Acme Corp"
tester: "Your Name"
start_date: "2026-01-01" # YYYY-MM-DD
end_date: "2026-12-31"
authorized_by: "CISO Name"
# ── Scope ─────────────────────────────────────────────────
scope:
base_urls:
- "https://target.com"
- "https://api.target.com" # Multi-URL supported
credentials: # Optional — greybox / whitebox
api_key: "" # Bearer token
username: "" # For login flow
password: ""
# ── Module toggles (all true by default) ──────────────────
modules:
web_security: true # Headers, CORS, sensitive paths
api_mapper: true # OpenAPI discovery, unauthenticated write ops
prompt_injection: true # LLM01 — direct + indirect injection
prompt_hunter: true # LLM07 — system prompt extraction
rag_tester: true # LLM04 — RAG poisoning
agent_tester: true # LLM06 — excessive agency
jwt_tester: true # Algorithm confusion, weak secrets
auth_tester: true # IDOR, priv-esc, session fixation
ssrf_tester: true # SSRF → cloud metadata
xxe_tester: true # XXE file read, SOAP, SVG
graphql_tester: true # Introspection, depth bombs
tls_transport: true
js_analysis: true # API keys in bundles
business_logic_tester: true
subdomain_takeover: true
trustworthiness: true # Hallucination rate, guardrails
ai_security: true
session_checker: true
# ── Testing parameters ────────────────────────────────────
testing:
request_delay_seconds: 0.3
max_requests_per_minute: 60
timeout_seconds: 15
max_concurrent_modules: 5
# ── Integrations ─────────────────────────────────────────
integrations:
teams_webhook_url: "" # Microsoft Teams — scan complete
slack_webhook_url: "" # Slack — scan complete
# ── AI Brain (optional) ───────────────────────────────────
# export ANTHROPIC_API_KEY=sk-ant-... # or GROQ_API_KEY
# Scanner works fully without AI keys — falls back to deterministic rules
SDK
Writing a Custom Module
Every XIPE module is a Python class with a run() method that returns List[Finding]. The orchestrator runs modules in parallel using concurrent.futures.ThreadPoolExecutor.
python# modules/my_module.py
import uuid
from typing import List
import httpx
from agent.finding import Finding, Severity, OWASPCategory, ScoringDetail
from utils.logger import PentestLogger
class MyModule:
def __init__(self, config: dict, http_client: httpx.Client,
logger: PentestLogger, brain_result=None):
self.config = config
self.client = http_client
self.logger = logger
self.brain = brain_result # XIPEBrain classification result
self.base_url = config["scope"]["base_urls"][0]
self.creds = config["scope"].get("credentials", {})
def run(self) -> List[Finding]:
findings = []
self.logger.info("MyModule", "Starting custom checks")
try:
resp = self.client.get(f"{self.base_url}/api/v1/secret-endpoint")
if resp.status_code == 200:
findings.append(Finding(
id=str(uuid.uuid4()),
module="my_module",
title="Unauthenticated access to secret endpoint",
severity=Severity.HIGH,
category=OWASPCategory.BROKEN_ACCESS,
description="The endpoint /api/v1/secret-endpoint returns 200 without credentials.",
recommendation="Require authentication on all non-public endpoints.",
endpoint=f"{self.base_url}/api/v1/secret-endpoint",
evidence=resp.text[:500],
scoring=ScoringDetail(
severity_score=8.0,
exploitability_score=9.0,
business_risk_score=7.0,
confidence_score=9.5,
auth_required=False,
).calculate(),
owasp_top10="A01 - Broken Access Control",
tags=["auth", "unauthenticated"],
verified=True,
))
except Exception as e:
self.logger.warning("MyModule", f"Request failed: {e}")
self.logger.success("MyModule", f"{len(findings)} findings")
return findings
Register in orchestrator.py — after writing your module, import it and add it to PentestOrchestrator._run_modules() inside the ThreadPoolExecutor block. Enable/disable via a toggle in config.yaml → modules.
python# agent/orchestrator.py — add to imports
from modules.my_module import MyModule
# Inside _run_modules() — add to futures dict:
if self.config["modules"].get("my_module", True):
futures[executor.submit(MyModule(
self.config, self.http_client, self.logger, brain_result
).run)] = "my_module"
# config.yaml — add toggle:
modules:
my_module: true
SDK
Finding Schema
The Finding dataclass is the universal output of every module. All fields are optional except title, severity, and endpoint.
| Field | Type | Description |
|---|
| id | str (uuid) | Auto-generated unique ID |
| module | str | Module that generated this finding |
| title | str | Short, descriptive title |
| severity | Severity enum | CRITICAL HIGH MEDIUM LOW INFO |
| category | OWASPCategory enum | OWASP Top 10 / API Top 10 / LLM Top 10 category |
| description | str | Full technical description of the finding |
| recommendation | str | Actionable remediation steps |
| endpoint | str | Affected URL or endpoint |
| request_snippet | str | None | HTTP request that triggered the finding |
| response_snippet | str | None | Relevant portion of the response |
| evidence | str | None | Proof of exploitability |
| scoring | ScoringDetail | HackerOne-style composite score (see Scoring section) |
| owasp_top10 | str | None | e.g. "A01 - Broken Access Control" |
| owasp_api_top10 | str | None | e.g. "API1 - BOLA" |
| owasp_llm_top10 | str | None | e.g. "LLM01 - Prompt Injection" |
| cwe | str | None | CWE identifier, e.g. "CWE-89" |
| tags | List[str] | Free-form tags for filtering |
| verified | bool | True if the finding was actively confirmed |
| false_positive_risk | str | LOW / MEDIUM / HIGH confidence in the finding |
python# Severity options
from agent.finding import Severity, OWASPCategory
Severity.CRITICAL # priority_score >= 9.0
Severity.HIGH # priority_score >= 7.0
Severity.MEDIUM # priority_score >= 4.5
Severity.LOW # priority_score >= 2.0
Severity.INFO # priority_score < 2.0
# OWASP LLM categories
OWASPCategory.PROMPT_INJECTION # LLM01
OWASPCategory.DATA_LEAKAGE # LLM02
OWASPCategory.DATA_POISONING # LLM04
OWASPCategory.EXCESSIVE_AGENCY # LLM06
OWASPCategory.SYSTEM_PROMPT # LLM07
# OWASP Top 10 categories
OWASPCategory.BROKEN_ACCESS # A01
OWASPCategory.INJECTION # A03
OWASPCategory.AUTH_BYPASS # A07
SDK
Scoring System
XIPE uses a HackerOne-inspired composite scoring model. The final priority_score (0–10) is a weighted average of 6 dimensions. Always call .calculate() after setting fields.
| Dimension | Weight | Description |
|---|
| severity_score | 25% | Base technical severity (0–10) |
| exploitability_score | 20% | How easy to exploit — 10 = one HTTP request |
| exposure_score | 15% | How exposed the asset is — 10 = fully public |
| business_risk_score | 20% | Potential business impact |
| asset_criticality_score | 10% | How critical is the affected asset |
| confidence_score | 10% | Certainty in the finding — 10 = confirmed RCE |
Modifiers: auth_required=True applies −15%, compensating_controls=True applies −20% to the raw score before bucketing.
pythonscoring = ScoringDetail(
severity_score=9.0, # Very severe
exploitability_score=8.5, # Easy to exploit
exposure_score=10.0, # Fully public endpoint
business_risk_score=9.0, # Can poison AI responses
asset_criticality_score=9.5, # System prompt = crown jewel
confidence_score=9.5, # Confirmed write access
auth_required=False, # No auth needed → no reduction
compensating_controls=False,
).calculate()
# → priority_score: 9.18 → CRITICAL bucket → remediation_priority: 1
Modules
Module Reference
All 20 modules available in v4.1. The Brain auto-selects relevant modules based on target classification. Disable any module in config.yaml → modules.
| Key | Class / File | What it tests | Coverage |
|---|
| web_security | WebSecurityModule | Security headers, CORS, cookies, sensitive paths (/.env, /.git), info disclosure, HTTP methods | A02, A05, HSTS, CSP |
| api_mapper | APIMapper | OpenAPI/Swagger parsing, unauthenticated write ops, SQL injection in JSON field names | API1, A03, JSON-key SQLi |
| prompt_hunter | PromptHunter | System prompt storage detection, write access test, hardcoded prompts in JS bundles, RAG indirect injection | LLM07 |
| ai_security | AISecurityModule | Auth on AI endpoints, default credentials, registration flow, platform fingerprinting | LLM01, LLM06 |
| prompt_injection | PromptInjectionTester | Direct + indirect prompt injection, 20+ templates per category, system prompt leakage probes | LLM01, LLM08 |
| rag_tester | RAGTester | RAG poisoning via document upload, data extraction from retrieval layer, tenant isolation bypass | LLM04 |
| agent_tester | AgentTester | Tool misuse, approval workflow bypass, chained agent action extraction, excessive agency | LLM06 |
| trustworthiness | TrustworthinessChecker | Hallucination rate, consistency across runs, safety guardrail bypass, PII in responses | AI-TRUST |
| auth_tester | auth_tester module | Login brute force, IDOR, privilege escalation, session fixation, password reset poisoning | A07, A01 |
| jwt_tester | jwt_tester module | Algorithm confusion (RS256→HS256), weak secrets, privilege escalation in claims, token replay | A07, JWT |
| ssrf_tester | ssrf_tester module | SSRF to cloud metadata (169.254.169.254), internal hosts, header-based SSRF (Host, X-Forwarded) | A10, SSRF |
| xxe_tester | xxe_tester module | XXE file read (/etc/passwd), SSRF via XML, SOAP payloads, SVG upload, XML bomb | A05, XXE |
| graphql_tester | graphql_tester module | Introspection, depth bombs, batch abuse (rate-limit bypass), dangerous mutations | API, GraphQL |
| tls_transport | TLSChecker | TLS version (SSLv3/TLS 1.0 detection), certificate validity, weak ciphers, HSTS | A02 |
| js_analysis | JSAnalyzer | API keys, secrets, and tokens exposed in JavaScript bundles | A02, A05 |
| business_logic_tester | business_logic_tester | Price manipulation, payment tampering, coupon abuse, IDOR on orders | A01, API6 |
| subdomain_takeover | subdomain_takeover | Dangling CNAMEs pointing to unclaimed S3, Azure, Heroku, GitHub Pages buckets | A05 |
| session_checker | SessionChecker | Cookie flags (HttpOnly, Secure, SameSite), session timeout, predictable session tokens | A07 |
| chain_engine | ChainEngine | Post-processing — links findings into attack narratives, calculates cumulative business impact | All |
| wordpress | WordPressScanner | Auto-activated on CMS detection — plugin/theme vulns, user enumeration, xmlrpc abuse | CMS |
API & Output
REST API — Triggering Scans
The XIPE Platform exposes a REST API for triggering scans, querying findings, and downloading reports programmatically. Authenticate with a JWT bearer token from POST /api/auth/login.
bashBASE=https://lgbg1u567l.execute-api.us-east-1.amazonaws.com
# 1. Authenticate
curl -X POST $BASE/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@org.com","password":"..."}'
# → { "token": "eyJ..." }
# 2. Launch a scan
curl -X POST $BASE/api/scans \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://target.com",
"client_name": "Acme Corp",
"engagement_id": "ENG-2026-001",
"modules": ["web_security", "api_mapper", "prompt_injection"]
}'
# → { "scan_id": "SCAN#abc123", "status": "running" }
# 3. Poll status
curl $BASE/api/scans/SCAN#abc123 \
-H "Authorization: Bearer <token>"
# 4. Get findings
curl $BASE/api/scans/SCAN#abc123/findings \
-H "Authorization: Bearer <token>"
# 5. Download PDF report
curl -L $BASE/api/scans/SCAN#abc123/report \
-H "Authorization: Bearer <token>" \
-o report.pdf
| Endpoint | Method | Description |
|---|
| /api/auth/login | POST | Get JWT token |
| /api/scans | POST | Launch a new scan |
| /api/scans | GET | List all scans (paginated) |
| /api/scans/{id} | GET | Scan status + metadata |
| /api/scans/{id}/findings | GET | All findings (JSON) |
| /api/scans/{id}/report | GET | PDF report (redirect to S3) |
| /api/clients | GET / POST | List / create clients |
| /api/stats/platform | GET | Platform-wide KPIs |
| /api/soc/sync | POST | Trigger SOC correlation (M365, GuardDuty, Obok, XIPE) |
| /api/soc/incidents | GET | List SOC incidents |
| /api/soc/agents | GET | List EDR agents |
| /api/soc/ingest | POST | Ingest EDR agent events (X-Agent-Key auth) |
API & Output
findings.json Schema
The canonical output format. Parse this to integrate XIPE findings into your own tooling, SIEM, or ticketing system.
json{
"engagement_id": "ENG-2026-001",
"target": "https://target.com",
"scan_duration_seconds": 112,
"findings_count": { "CRITICAL": 3, "HIGH": 7, "MEDIUM": 12, "LOW": 6, "INFO": 4 },
"findings": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"module": "prompt_hunter",
"timestamp": "2026-04-08T14:22:11Z",
"title": "System prompt storage writable without authentication",
"severity": "CRITICAL",
"category": "LLM07 - System Prompt Leakage",
"description": "POST /api/v1/agents/config accepts writes without a valid JWT...",
"recommendation": "Require authentication and authorization checks on all prompt-writing endpoints.",
"endpoint": "https://target.com/api/v1/agents/config",
"evidence": "HTTP 200 OK — system_prompt field updated",
"scoring": {
"priority_score": 9.4,
"final_priority_bucket": "Critical",
"severity_score": 10.0,
"exploitability_score": 9.5,
"business_risk_score": 9.8,
"confidence_score": 9.5,
"remediation_priority": 1,
"explanation": "Priority Score: 9.4/10"
},
"standards": {
"owasp_top10": null,
"owasp_api_top10": "API1 - BOLA",
"owasp_llm_top10": "LLM07 - System Prompt Leakage",
"cwe": "CWE-284"
},
"tags": ["system-prompt", "unauthenticated", "llm"],
"false_positive_risk": "LOW"
}
],
"attack_chains": [
{
"chain_id": "chain-001",
"title": "API Docs → SQLi → DB Compromise → AI Takeover",
"steps": ["finding-id-1", "finding-id-2", "finding-id-3"],
"business_impact": "Full DB read/write. System prompts modifiable silently.",
"composite_score": 9.8
}
]
}
API & Output
Webhooks & Notifications
XIPE sends a notification at scan completion. Configure the webhook URL in config.yaml → integrations. Microsoft Teams and Slack are supported.
Teams only — no Adaptive Cards. Use the MessageCard format. Adaptive Cards require O365 Connectors approval; MessageCard works with any incoming webhook URL.
yaml# config.yaml
integrations:
teams_webhook_url: "https://outlook.office.com/webhook/..."
slack_webhook_url: "https://hooks.slack.com/services/..."
json// Teams MessageCard payload (sent by reporting/teams_notifier.py)
{
"@type": "MessageCard",
"@context": "https://schema.org/extensions",
"themeColor": "FF2200",
"summary": "XIPE Scan Complete — ENG-2026-001",
"sections": [{
"activityTitle": "🔴 XIPE — Scan Complete",
"activitySubtitle": "Acme Corp · 28 findings",
"facts": [
{ "name": "CRITICAL", "value": "3" },
{ "name": "HIGH", "value": "7" },
{ "name": "Duration", "value": "1m 52s" }
]
}],
"potentialAction": [{
"@type": "OpenUri",
"name": "View Report",
"targets": [{ "os": "default", "uri": "https://xipe.socaiops.com/scans/..." }]
}]
}
SOC alerts (EDR events) — When an EDR agent detects a HIGH or CRITICAL event, XIPE creates a SOC incident and sends a Teams MessageCard automatically via TEAMS_SOC_WEBHOOK (ECS env var, separate from scan notifications).