r0ms3c/aisecpulse
GitHub: r0ms3c/aisecpulse
Stars: 0 | Forks: 1
# AiSecPulse
[](https://python.org)
[](LICENSE)
[]()
[]()
[](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
[](https://atlas.mitre.org/)
[](https://r0ms3c.github.io/aisecpulse/)
## Demo
- ✅ **[View live detection report](https://r0ms3c.github.io/aisecpulse/demo/report.html)**
The demo shows the actual HTML report generated by the pipeline after processing all 96 events -- pipeline summary, severity breakdown by level, detection breakdown by method (rule-based, anomaly, or both), and the full alert table with per-alert scores, detection type, and rules fired.
## Overview
Modern enterprises are rapidly adopting AI systems -- chatbots, copilots, and autonomous agents. These systems introduce a new attack surface that traditional security tools were not built to monitor.
**AiSecPulse** is a production-inspired detection platform that acts as a centralised engine for monitoring AI interactions. It processes events from chat and agentic AI systems, extracts risk features, applies layered detection logic, and generates structured alerts with severity scores -- simulating how a real SOC team would approach AI security monitoring.
This project is not just code. Every detection rule, every feature, and every architectural decision maps back to a documented attack vector from the frameworks below.
## Research Foundation
This project was built on top of three authoritative AI security frameworks:
| Framework | Scope | Relevance to this project |
|---|---|---|
| [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/) | Top 10 risks in LLM applications | Defines the attack vectors detected: LLM01 Prompt Injection, LLM02 Sensitive Information Disclosure, LLM06 Excessive Agency, LLM07 System Prompt Leakage |
| [OWASP Agentic skills Top 10](https://owasp.org/www-project-agentic-skills-top-10/) | Threats specific to agentic AI systems | Informs the agent detection layer -- action validation, blast radius, privilege escalation patterns |
| [MITRE ATLAS](https://atlas.mitre.org/) | Adversarial threat landscape for AI systems | Informs the feature engineering and obfuscation detection -- evasion techniques documented in the ATLAS knowledge base |
### OWASP LLM risks covered
| # | Risk | Coverage |
|---|---|---|
| LLM01 | Prompt Injection | Full -- keyword detection, instruction density, obfuscation |
| LLM02 | Sensitive Information Disclosure | Partial -- exfiltration patterns in agent actions |
| LLM06 | Excessive Agency | Full -- dangerous action detection, privilege escalation |
| LLM07 | System Prompt Leakage | Partial -- keyword patterns targeting system prompt extraction |
| LLM03-LLM05, LLM08-LLM10 | Other risks | Out of scope for v1 -- listed as v2 enhancements |
## Detection Targets
| Threat | Event Type | OWASP / MITRE Reference |
|---|---|---|
| Prompt Injection | Chat + Agent | LLM01 |
| Jailbreak and Role Override | Chat | LLM01 |
| System Prompt Extraction | Chat | LLM07 |
| Social Engineering | Chat | LLM01, ATLAS AML.T0054 |
| Obfuscation (base64, zero-width) | Chat | ATLAS AML.T0054.000 |
| Data Exfiltration | Agent | LLM02, LLM06 |
| Privilege Escalation | Agent | LLM06 |
| Destructive Actions | Agent | LLM06 |
## Architecture
data/sample_events.json
|
v
+------------------------+
| ETL Pipeline | etl/ingest.py, etl/normalize.py
+------------------------+
|
v
+------------------------+
| Feature Extraction | features/extractor.py
+------------------------+
|
v
+------------------------------------------------+
| Detection Engine |
| detectors/rules.py (rule-based) |
| detectors/anomaly.py (isolation forest) |
| detectors/scorer.py (weighted combiner) |
+------------------------------------------------+
|
v
+------------------------+
| Alerts + Report | alerts/alerting.py, reports/generator.py
+------------------------+
## Detection Engine
Three layers run on every event and are combined into a single final risk score.
### Layer 1 -- Rule-Based (detectors/rules.py)
Fast, deterministic detection using keyword patterns, action blocklists, and structural heuristics. Fires on known attack signatures. High precision, zero latency.
### Layer 2 -- Anomaly Detection (detectors/anomaly.py)
Unsupervised Isolation Forest trained on the full feature matrix. Learns what normal traffic looks like, then flags statistical deviations. Catches novel attacks that no rule covers yet.
### Layer 3 -- Scorer (detectors/scorer.py)
Weighted combination of both signals into a single final score:
final_score = (rule_score x 0.65) + (anomaly_score x 0.35)
Severity classification:
0.00 - 0.39 -> LOW logged silently
0.40 - 0.69 -> MEDIUM logged with warning
0.70 - 0.89 -> HIGH alert raised
0.90 - 1.00 -> CRITICAL alert raised and flagged
## Project Structure
aisecpulse/
|-- README.md
|-- requirements.txt
|-- main.py # Entry point -- runs the full pipeline
|-- config.yaml # All thresholds, weights, keywords, paths
|-- data/
| +-- sample_events.json # 96 labelled events -- included in repo
|-- etl/
| |-- ingest.py # Load and parse raw events
| +-- normalize.py # Validate schema, clean and type events
|-- features/
| +-- extractor.py # Feature engineering -- 7 features per event
|-- detectors/
| |-- rules.py # Rule-based detection layer
| |-- anomaly.py # Isolation Forest anomaly detection
| +-- scorer.py # Weighted score combiner + severity classifier
|-- alerts/
| +-- alerting.py # Alert generation and enrichment
|-- logs/
| +-- detections.log # Runtime log (generated, not committed)
+-- reports/
|-- generator.py # HTML report builder
+-- report.html # Generated report (run pipeline to produce)
## Dataset
It contains **96 fully labelled synthetic events** with no real users or sensitive information. Clone and run immediately.
| Split | Count | Description |
|---|---|---|
| Normal | 55 | Legitimate chat queries and routine agent actions |
| Injection | 41 | Prompt injections, jailbreaks, exfiltration, destructive actions |
| Chat events | 58 | Human to AI interactions |
| Agent events | 38 | AI to API / action executions |
**Attack categories in the dataset:**
- Classic injection (ignore all previous instructions, DAN, role override)
- Social engineering (grandma trick, fictional framing, roleplay bypass)
- Obfuscation (base64 encoded payloads, zero-width unicode character splitting)
- Agentic attacks (file exfiltration, destructive SQL, privilege escalation, remote code execution)
## Quick Start
# 1. Clone the repository
git clone https://github.com/r0ms3c/aisecpulse.git
cd aisecpulse
# 2. Create a virtual environment
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run the detection pipeline
python3 main.py
The pipeline will process `data/sample_events.json`, run all detection layers, print alerts to the terminal, write logs to `logs/detections.log`, and generate `reports/report.html`.
## Requirements
Python 3.10+
scikit-learn
pandas
pyyaml
loguru
## Sample Output
Running `python3 main.py` produces output like this:
2025-05-01 10:00:00 | INFO | AiSecPulse -- AI Security Detection Pipeline
2025-05-01 10:00:00 | INFO | Phase 1 complete (96 events loaded)
2025-05-01 10:00:00 | INFO | Phase 2 complete (96 feature vectors extracted)
2025-05-01 10:00:00 | INFO | Rules -- 40/96 flagged
2025-05-01 10:00:00 | INFO | Anomaly -- 17/96 flagged
2025-05-01 10:00:00 | INFO | Scoring -- LOW=56 | MEDIUM=1 | HIGH=37 | CRITICAL=2
2025-05-01 10:00:00 | WARNING | [CRITICAL] agent | agent_305 | score=1.0
rules=keyword_hit + dangerous_action + instruction_density
2025-05-01 10:00:00 | WARNING | [CRITICAL] chat | user_114 | score=0.983
type=rule + anomaly
2025-05-01 10:00:00 | INFO | Pipeline complete -- 39 alerts raised
2025-05-01 10:00:00 | INFO | Report -> reports/report.html
View the full interactive report: **[Live Demo](https://r0ms3c.github.io/aisecpulse/)**
## Event Schema
Every event processed by the platform follows this unified schema:
{
"timestamp" : "2025-05-01T10:00:00Z",
"source" : "sample",
"type" : "chat | agent",
"user_id" : "user_001",
"prompt" : "...",
"response" : "...",
"action" : null,
"label" : "normal | injection"
}
`action` is only populated for agent events. Chat events always carry `null`.
## Design Decisions
**Why rule + anomaly instead of a classifier?**
A supervised classifier requires labelled training data, a train/test split, and ongoing retraining as attacks evolve. Rules + Isolation Forest achieves strong detection with no training data requirements -- rules handle known patterns deterministically, anomaly detection handles unknown ones statistically. A classifier is listed as a v2 enhancement.
**Why config-driven?**
Every threshold, keyword, and weight lives in `config.yaml`. Nothing is hardcoded. You can tune the entire detection behaviour -- add keywords, adjust severity thresholds, reweight the scorer -- without touching a single line of Python.
**Why separate ETL, features, and detectors?**
Each layer has a single responsibility. ETL produces clean events. Features produces numeric vectors. Detectors consume vectors. This makes each component independently testable and replaceable -- swap Isolation Forest for a transformer model without touching ETL or alerting.
## Planned Enhancements (v2)
- [ ] Supervised ML classifier (fine-tuned sentence transformer)
- [ ] Indirect prompt injection via RAG/retrieval context
- [ ] LLM05 -- Improper Output Handling detection (response analysis)
- [ ] LLM10 -- Unbounded Consumption detection (token exhaustion patterns)
- [ ] Real-time streaming mode
- [ ] SIEM integration (Splunk / Elastic export format)
- [ ] REST API wrapper for pipeline integration
## References
- [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
- [OWASP Agentic AI Threats](https://owasp.org/www-project-agentic-skills-top-10/)
- [MITRE ATLAS -- Adversarial Threat Landscape for AI Systems](https://atlas.mitre.org/)
## Author
**r0ms3c** -- Security Engineer
[GitHub](https://github.com/r0ms3c)
## License
MIT License -- see [LICENSE](LICENSE) for details.