TraceAI Engine is a local-first AI/ML security operations workspace for suspicious email, endpoint/log evidence, and multi-evidence case investigation. It combines deterministic security logic, IOC extraction, synthetic ML anomaly signals, optional controlled enrichment, shared AI triage, local RAG/Ollama assistance, and sanitized case report export.
TraceAI Engine is a public local-first AI security investigation and risk triage platform. The repository folder name remains ai-security-lab.
The project exists to show how an analyst can move from user-reported email or endpoint evidence into a selected case, review explainable triage, ask a local Copilot for guidance, and export a human-reviewed case report without sending raw evidence to online AI. The implementation uses fake/sample data, transparent local logic, bounded summaries, and tests so the workflows are easy to review, explain, and extend.
TraceAI Engine is the main product in this repository. The /labs folder contains earlier standalone AI security labs that helped build the foundation for the product.
| Path / Workspace | What It Does | Engineering Signal |
|---|---|---|
dashboard / TraceAI Engine |
Streamlit product workspace with Overview, Email Investigation, Threat Evidence Workbench, Case Investigation, AI Trust Boundary, AI triage, TraceAI Copilot, and case report export. | AI SOC product design, local-first workflows, safe evidence handling, dashboard UX |
| Overview workspace | Product summary, workspace entry points, local AI/security readiness, and sample project access. | Executive demo flow, navigation, readiness indicators |
| Email Investigation workspace | Parses suspicious email samples, extracts indicators, flags phishing signals, supports optional controlled enrichment, applies AI triage, and can add summarized evidence to a selected case. | Email security, phishing triage, safe enrichment boundaries, user/SOC actions |
| Threat Evidence Workbench workspace | Analyzes fake/sample endpoint, log, process, sign-in, and alert evidence; detects encoded PowerShell, payload download behavior, suspicious parent-child process chains, and persists the latest session analysis. | Evidence handling, IOC extraction, MITRE ATT&CK, KQL, Copilot-safe summaries |
| Case Investigation workspace | Supports multiple session-state cases, selected case dropdown, case title editing, manual severity vs AI triage severity, evidence collection, combined IOCs/entities, timeline, attack path, MITRE mapping, Freshservice-style notes, KQL, active-case Copilot handoff, and Markdown/PDF case report export. | Case management concepts, SOC investigation workflow, analyst documentation |
| AI Triage & Analyst Decision Engine | Deterministic offline triage across Email, Evidence, Case, and Copilot contexts. Returns severity, score, confidence, decision, recommended queue, risk factors, actions, and limitations. | Explainable triage, analyst decision support, human review boundaries |
| TraceAI Copilot workspace | Local Ollama-powered assistant that uses selected case/email/evidence context, repo playbooks, KQL references, automation notes, and RAG retrieval to explain triage decisions and draft analyst guidance. | Local RAG, Ollama, source citations, guardrails, safe AI assistance |
| Path | What It Does | Engineering Signal |
|---|---|---|
email_analyzer |
Parses fake/sample email evidence for local phishing triage, IOCs, risk scoring, and optional provider lookup of extracted indicators. | Email threat analysis, safe enrichment boundaries, analyst recommendations |
evidence_analyzer |
Parses fake/sample JSON, CSV, TXT, or LOG evidence and generates IOC-focused local threat summaries for the dashboard. | Evidence handling, IOC extraction, local parsing, threat rules, Copilot-safe context summaries |
security_copilot |
Local-first Security Copilot that retrieves repo context and can answer through Ollama using qwen2.5:3b. |
Local RAG, Ollama, source citation, guardrails, safe AI usage |
automation |
Sample-safe Microsoft Security automation library with KQL, read-only PowerShell references, and Freshservice-style ticket templates. | Sentinel/Defender hunting, read-only investigation scripts, ticket documentation |
docs/soc_playbooks |
SOC playbooks for suspicious PowerShell, risky sign-in, phishing, malware, impossible travel, and mass deletion. | Investigation process, escalation criteria, MITRE ATT&CK, analyst workflow |
| Path | What It Does | Engineering Signal |
|---|---|---|
labs/01-ai-soc-assistant |
Generates SOC triage reports from fake Microsoft Defender/Sentinel-style alert JSON files. | SOC investigation, MITRE ATT&CK, KQL, analyst notes, escalation handling |
labs/02-ai-phishing-analyzer |
Reviews fake user-reported phishing emails and produces risk ratings, indicators, containment steps, and ticket notes. | Email security, phishing triage, authentication checks, user response guidance |
labs/03-prompt-injection-lab |
Evaluates safe sample prompt injection tests and maps findings to AI security concepts. | OWASP LLM Top 10, MITRE ATLAS-style mapping, defensive AI patterns |
labs/04-ai-vendor-risk-toolkit |
Scores fake AI vendor profiles and generates Markdown risk reports. | Vendor risk governance, IAM review, data protection, logging, compliance review |
labs/05-ml-anomaly-detection |
Uses IsolationForest when available, with a deterministic fallback, to score fake/synthetic security logs for unusual activity. | ML-assisted SOC triage, anomaly scoring, human review limits |
TraceAI Engine shows how security teams can explore AI-assisted SOC workflows without relying on black-box tooling or live production data. The repository models how analysts can triage alerts, investigate suspicious emails, extract IOCs, correlate evidence into cases, compare manual severity with explainable AI triage severity, test prompt injection defenses, review AI vendor controls, ask a local Copilot for source-cited guidance, and export a sanitized case report.
The project is intentionally local, transparent, and reviewable. It is designed for hands-on learning, security engineering review, and future extension into approved enterprise integrations.
TraceAI Engine v1.0 is a public release centered on local-first AI security investigation workflows. It includes:
- Email Investigation
- Evidence Workbench
- Case Investigation with local case persistence
- AI triage and severity scoring
- IOC/entity extraction
- MITRE ATT&CK mapping
- KQL hunting guidance
- Missing evidence analysis
- Freshservice-style note generation
- TraceAI Copilot with local RAG and Ollama
- Deterministic routing for common Copilot prompts
- Suggested Copilot prompts
- Interactive evidence relationship graph
- Markdown/PDF incident report export
- Trust boundary and guardrail wording
The GitHub Pages landing page is available in docs/index.html. It is a static project page only; the Streamlit product still runs locally.
- Email Investigation: Parses fake/sample email evidence, extracts IOCs, flags phishing signals, shows user/SOC guidance, supports optional controlled enrichment, applies AI triage, and can add a summarized email artifact to a selected case.
- Threat Evidence Workbench: Analyzes fake/sample JSON, CSV, TXT, and LOG evidence; extracts IOCs and investigation artifacts; detects suspicious behaviors such as encoded PowerShell, payload download behavior, risky sign-in indicators, and suspicious process chains; persists the latest session analysis; applies AI triage; and can add summarized evidence to a selected case.
- Multiple Case Investigation Workspace: Maintains multiple cases, supports local save/load of sanitized case summaries, selected-case switching, case title editing, manual case severity, AI triage severity, evidence collection, combined IOCs/entities, timeline, attack path, MITRE mapping, Freshservice-style ticket note, KQL hunting queries, and active-case handoff to TraceAI Copilot.
- AI Triage & Analyst Decision Engine: Works offline and deterministically across Email, Evidence, Case, and Copilot contexts. It returns severity, score, confidence, decision, recommended queue, risk factors, supporting evidence, recommended actions, limitations, and a human review reminder.
- TraceAI Copilot: Uses local Ollama plus local RAG over repo docs, playbooks, KQL, PowerShell notes, ticket templates, and selected session summaries. It explains triage decisions, drafts analyst notes, generates KQL-style hunting guidance, and does not require raw evidence.
- Markdown/PDF Case Report Export: Exports the active selected case as a sanitized TraceAI Engine Case Report. Reports include summaries, AI triage, evidence collection, IOCs, timeline, MITRE mapping, KQL, actions, ticket note, and trust boundary notes without raw evidence.
- AI Trust Boundary: Shows local-first state, controlled enrichment behavior, raw evidence boundaries, provider status, and human review requirements.
- Analyze a suspicious email in Email Investigation.
- Analyze endpoint, identity, or log evidence in Threat Evidence Workbench.
- Add summarized evidence to the active selected case.
- Review AI Triage & Analyst Decision Engine severity, confidence, decision, risk factors, and limitations.
- Ask TraceAI Copilot for case-aware guidance, KQL, or a Freshservice-style note.
- Export a sanitized TraceAI Engine Case Report as Markdown or PDF.
- Python automation with readable, beginner-friendly structure
- Rule-based security analysis, scoring, validation, and report generation
- Streamlit dashboard design for a local AI SOC product experience
- SOC alert triage and analyst documentation
- AI triage and explainable analyst decision support
- Multiple case workflow and session-state case management
- Sanitized Markdown/PDF report generation
- Microsoft Defender and Microsoft Sentinel-style investigation workflows
- KQL hunting query development
- User-reported phishing analysis and containment planning
- IOC extraction from email, JSON, CSV, TXT, and LOG evidence
- Optional online reputation enrichment with clear data boundaries
- IAM, SSO, MFA, RBAC, logging, retention, and deletion control review
- AI prompt injection testing and defensive response design
- AI vendor risk and governance documentation
- Synthetic ML anomaly detection with human review warnings
- Unit testing with
unittest - GitHub Actions CI for test automation
- Local-first RAG orchestration with TF-IDF retrieval, Ollama, guardrails, and source-cited answers
- Local evidence upload handling with safe parsing, sensitive-content blocking, and session-only summaries
- SOC playbook writing, KQL hunting references, read-only PowerShell investigation samples, and Freshservice-style ticket templates
- MITRE ATT&CK for SOC alert, phishing, identity, endpoint, and evidence mapping
- MITRE ATLAS-style concepts for AI threat scenarios
- OWASP LLM Top 10 for prompt injection and AI application risk categories
- AI vendor risk and security governance concepts
- SOC automation, triage consistency, escalation decisions, and ticket updates
- Secure local development practices using fake/sample data only
- ML-assisted triage concepts with human review limitations
- Retrieval-augmented generation concepts with a local Ollama LLM provider and CI-safe mock mode
- Microsoft Sentinel / Defender-style SOC investigation resources using sample-safe placeholders only
See docs/framework_mapping.md for the cross-project mapping.
The current dashboard workflow is:
Email Investigation / Threat Evidence Workbench
|
v
Summarized evidence and extracted IOCs
|
v
Multiple Case Investigation Workspace
|
v
AI Triage & Analyst Decision Engine
|
v
Case-aware TraceAI Copilot
|
v
Analyst decision support / ticket note / KQL / actions
Deterministic logic handles parsing, IOC extraction, risk scoring, KQL generation, safe summaries, session-state case handling, and safety controls. The ML module handles synthetic anomaly detection signals. Local LLM/RAG handles explanation, summarization, analyst guidance, and Copilot-style workflows. The AI triage engine is deterministic and does not require Ollama.
See docs/architecture_overview.md for more detail.
This project intentionally uses a hybrid approach. Not every calculation depends on an LLM. Deterministic logic is used for reliable parsing, IOC extraction, scoring, KQL generation, session summaries, case labels, and safety controls. ML is used for anomaly detection on synthetic security logs. Local LLM/RAG is used for explanation, summarization, analyst guidance, and Copilot-style workflows. AI triage provides explainable decision support across Email Investigation, Threat Evidence Workbench, Case Investigation, and TraceAI Copilot.
TraceAI Engine runs from the root-level dashboard and core modules. Supporting labs can still run from their folders under /labs. Labs 1-4 use JSON inputs and Python standard-library logic. Lab 5 uses a synthetic CSV input with pandas and scikit-learn when available.
On Windows, use py -3 if python is not available.
On Windows, start the full dashboard and configure the Ollama-powered TraceAI Copilot with:
.\start-dashboard.ps1The launcher sets local Copilot environment variables, checks Ollama at http://localhost:11434, pulls qwen2.5:3b if needed, preloads the model, and starts Streamlit. See docs/local_startup_guide.md for setup and troubleshooting.
TraceAI Copilot requires Ollama for real local AI answers. The default model is qwen2.5:3b; if Ollama or the model is unavailable, the dashboard shows setup-required guidance instead of silently falling back to mock mode.
cd .\labs\01-ai-soc-assistant
python .\triage_assistant.py .\sample-inputs\risky-sign-in.json
python .\triage_assistant.py --batchcd .\labs\02-ai-phishing-analyzer
python .\phishing_analyzer.py .\sample-inputs\microsoft-365-password-reset.json
python .\phishing_analyzer.py --batchcd .\labs\03-prompt-injection-lab
python .\prompt_injection_lab.py .\sample-inputs\direct-instruction-override.json
python .\prompt_injection_lab.py --batchcd .\labs\04-ai-vendor-risk-toolkit
python .\vendor_risk_assessment.py .\sample-inputs\fabrikam-support-copilot.json
python .\vendor_risk_assessment.py --batchcd .\labs\05-ml-anomaly-detection
python -m pip install -r requirements.txt
python .\anomaly_detector.py --input .\sample-inputs\synthetic_signin_logs.csv --output .\sample-output\anomaly_report.mdcd .\security_copilot
python -m pip install -r requirements.txt
ollama pull qwen2.5:3b
ollama run qwen2.5:3b
python .\copilot_assistant.py --question "Summarize the SOC triage guidance for suspicious script activity."For CI or demo environments without Ollama, use mock mode:
$env:COPILOT_TEST_MODE="true"
python .\copilot_assistant.py --question "What are the limitations of this lab?"Batch mode for Projects 1-4 processes every JSON file in each project's sample-inputs folder. By default, generated reports are saved under sample-output/batch.
The Streamlit dashboard is branded as TraceAI Engine and is available in dashboard/.
It provides a local-first SOC workspace with five focused areas:
| Workspace | Purpose |
|---|---|
| Overview | Product summary, workspace entry points, and local AI/security readiness. |
| Email Investigation | User-reported phishing and suspicious email triage with local analysis, IOC extraction, optional controlled enrichment, AI triage, and selected-case handoff. |
| Threat Evidence Workbench | Local analysis of fake/sample JSON, CSV, TXT, and LOG evidence with session persistence, IOC extraction, risk scoring, AI triage, and selected-case handoff. |
| Case Investigation | Multiple session-state cases with selected case dropdown, case title editing, manual severity vs AI triage severity, evidence correlation, timeline, attack path, KQL, and ticket notes. |
| TraceAI Copilot | Local Ollama/RAG assistant that uses selected case/email/evidence summaries, playbooks, KQL references, automation notes, and source citations. |
Dashboard includes:
- compact local AI and security readiness status
- AI Trust Boundary indicators
- local-only evidence parsing with session-only summaries
- IOC extraction
- optional online enrichment for extracted indicators only
- AI triage with severity, confidence, decision, queue, risk factors, actions, and limitations
- multiple session-state cases with manual severity kept separate from AI triage severity
- active-case Markdown and PDF report export
- SOC playbook, KQL, read-only PowerShell, and Freshservice-style ticket-template references
- TraceAI Copilot using Ollama and
qwen2.5:3b - mock/test mode for CI and demo environments without Ollama
- raw/debug details hidden by default
Recommended Windows startup from the repository root:
.\start-dashboard.ps1Manual fallback from the repository root:
python -m pip install -r .\dashboard\requirements.txt
python -m streamlit run .\dashboard\app.pyOnline enrichment is disabled by default.
When explicitly enabled and provider API keys are configured, the Email Investigation workspace can enrich extracted indicators with reputation providers.
Current provider support:
| Provider | Scope | Safety Model |
|---|---|---|
| Google Safe Browsing | Extracted URLs only | Lookup only; no raw email body, headers, or attachments sent. |
| URLhaus | Extracted URLs only | Lookup only; URL reputation enrichment. |
| VirusTotal | URLs, domains, public IPs, and hashes | Lookup only; no file uploads and no URL submissions. |
| AbuseIPDB | Public IP addresses only | Private, internal, and test-net IPs are excluded. |
| urlscan.io | Existing public/historical scan search only | Search only; no new scan submission. |
Online enrichment sends only selected extracted indicators such as URLs, domains, public IPs, or hashes to configured providers.
It does not send:
- raw email body
- raw email headers
- attachments
- uploaded files
- secrets
- tenant data
- company/client/vendor confidential data
If enrichment is disabled or API keys are missing, the dashboard continues to run in offline local-analysis mode.
Included sample evidence is fake, synthetic, or lab-safe:
- fake phishing email samples in
email_analyzer/sample-inputs - fake JSON, CSV, TXT, and LOG evidence in
evidence_analyzer/sample-inputs - synthetic sign-in logs in
labs/05-ml-anomaly-detection/sample-inputs - fake Defender/Sentinel-style alerts in
labs/01-ai-soc-assistant/sample-inputs - fake vendor and prompt-injection examples in the supporting lab folders
Do not add real company, client, tenant, vendor, confidential, or production data.
Screenshots are planned.
Recommended screenshots:
- Overview workspace
- Email Investigation verdict/enrichment
- Evidence Workbench analysis
- Case Investigation workspace
- TraceAI Copilot answer with sources
- GitHub Actions passing tests
See assets/screenshots/README.md for capture guidance.
Run all project tests from the repository root:
python .\run_all_tests.pyOr on Windows:
py -3 .\run_all_tests.pyGitHub Actions runs the full test suite on push and pull request using .github/workflows/python-tests.yml. See docs/testing_guide.md for details.
All data in the repo is fake/sample only.
Do not add real company, client, vendor, tenant, production, or confidential data.
The tools do not connect to Microsoft Defender, Sentinel, Entra ID, Exchange Online, Freshservice, vendor portals, or live security systems.
TraceAI Copilot uses local repo context and local Ollama when enabled.
Tests use mock mode and do not require Ollama.
Email Investigation supports optional online reputation enrichment only when explicitly enabled and API keys are configured. In that mode, only extracted indicators are sent to configured providers.
Raw email content, raw headers, attachments, and uploaded files are not sent externally.
Threat Evidence Workbench and Case Investigation pass only bounded summarized evidence context to TraceAI Copilot. They do not permanently save uploaded files, index raw uploaded files into RAG, or send evidence to external services.
Cases can be saved and loaded as local sanitized JSON summaries, but there is no database persistence, auth/RBAC, production ticketing integration, or live Microsoft tenant integration. Human analyst review is required before containment, escalation, user notification, or ticket closure.
I built TraceAI Engine, a local-first AI SOC investigation workspace that supports an analyst from suspicious email or endpoint evidence through case triage, Copilot-assisted investigation, and sanitized case report export. The platform uses deterministic security logic for reliable extraction and scoring, ML for synthetic anomaly signals, and local LLM/RAG for investigation reasoning and analyst assistance. An AI triage engine provides explainable severity, confidence, decision, and recommended actions across Email Investigation, Threat Evidence Workbench, Case Investigation, and TraceAI Copilot.
- Architecture overview
- Security design notes
- Framework mapping
- Demo walkthrough
- Demo script
- Testing guide
- Local startup guide
- Threat Evidence Workbench
- SOC playbook library
- Microsoft Security automation library
- Add case persistence and saved case history.
- Add a triage queue overview.
- Add richer demo evidence packs.
- Improve Copilot response modes and streaming behavior.
- Add a sample report gallery and dashboard screenshots.
- Add optional approved enterprise integration examples as documentation only.