How abdullahjadoon34/access-anomaly-analyzer works
Purpose and Entry Point
Access Anomaly Analyzer is a local Streamlit security-analysis prototype. It ingests authentication logs, deterministically identifies suspicious events, and presents prioritized SOC guidance. The executable entry point is app.py; users launch it with Streamlit. The bundled demo input is access_logs.csv.
Application and UI Orchestration
app.py contains the application’s primary control flow: CSV loading, rule evaluation, risk presentation, analyst-facing incident views, and optional narrative generation. Streamlit is the runtime/UI boundary, allowing the same process to render verified findings and accept analyst interaction.
Grounding paths:
• app.py
• RUN_INSTRUCTIONS.txt
• requirements.txt
Log Data Boundary
The system treats CSV access events as its input contract. The checked-in dataset supplies 308 synthetic events with five planted incidents; it is intended for repeatable demonstrations rather than production log collection. Dataset generation is separated from analysis, enabling reproducible test/demo inputs through a fixed seed.
Grounding paths:
• access_logs.csv
• gen_data.py
Deterministic Detection Engine
Detection is intentionally rule-based and resides in the application layer. Its output is the trusted boundary for downstream AI: only events that pass explicit detection rules become high-risk findings. The rules cover impossible travel, brute-force attempts, service-account misuse, privilege escalation, and anonymizer/Tor-origin activity.
Grounding paths:
• app.py
• access_logs.csv
Risk Prioritization and Analyst Views
Verified rule outputs are transformed into a structured risk panel and incident-oriented views. This stage is responsible for exposing findings in a form suitable for SOC triage, including prioritized response recommendations. It is distinct from AI prose generation: the panel remains available when offline or without an API key.
Grounding paths:
• app.py
• screenshots/homapage.png
• screenshots/incident_summary.png
AI Narrative Boundary
An LLM is an optional downstream consumer of verified detections, not a detector. When an Anthropic API key is configured, the app can generate an incident summary and fuller SOC narrative. Claims not directly grounded in detection output are labeled [Inference]; without external access, the app uses a built-in demo brief.
Grounding paths:
• app.py
• screenshots/brief_summary.png
• README.md
Infrastructure and External Services
The base deployment is a local Python process using Streamlit and runs offline. The only stated external integration is Claude/Anthropic, activated through the ANTHROPIC_API_KEY environment variable. No separate backend, database, queue, or cloud infrastructure is represented in the repository.
Grounding paths:
• requirements.txt
• RUN_INSTRUCTIONS.txt
• app.py
Main entry points: app.py Streamlit Runtime · access_logs.csv Access Log CSV · requirements.txt Python Dependencies · RUN_INSTRUCTIONS.txt Run Instructions
Components 14
Local Streamlit App
Offline-first analysis runs in one Python process.
- Streamlit Runtime · Launches and renders the local application.
app.py - Application Flow · Coordinates loading, detection, prioritization, views, and narratives.
app.py - Detection Rules · Detects impossible travel, brute force, misuse, escalation, and anonymizer activity.
app.py - Verified Findings · Only rule-passing events may feed AI output.
app.py - Risk Prioritization · Structures and prioritizes findings with response guidance.
app.py - Incident Views · Presents risk panels and incident-oriented analyst views.
app.py - Python Dependencies
requirements.txt - Run Instructions
RUN_INSTRUCTIONS.txt
Demo Data
Repeatable synthetic authentication-log input.
- Access Log CSV · 308 synthetic events including planted incidents.
access_logs.csv - Dataset Generator · Produces reproducible demo input with a fixed seed.
gen_data.py
Optional AI
Narrative generation consumes verified findings only.
- Narrative Generator · Uses a built-in demo brief when external AI is unavailable.
app.py - Claude / Anthropic · Enabled only when ANTHROPIC_API_KEY is configured.
Other components
- SOC Analyst
- Project Documentation
README.md
Connections 15
- SOC Analyst → Streamlit Runtime: launches and interacts with
- Run Instructions → Streamlit Runtime: documents launch
- Python Dependencies → Streamlit Runtime: provides dependencies
- Streamlit Runtime → Application Flow: runs
- Dataset Generator → Access Log CSV: generates
- Access Log CSV → Application Flow: loads events
- Application Flow → Detection Rules: evaluates
- Detection Rules → Verified Findings: emits suspicious events
- Verified Findings → Risk Prioritization: prioritizes
- Risk Prioritization → Incident Views: renders guidance
- Incident Views → SOC Analyst: presents triage
- Verified Findings → Narrative Generator: grounds input
- Claude / Anthropic → Narrative Generator: generates when configured
- Narrative Generator → Incident Views: adds incident brief
- Project Documentation → Narrative Generator: documents AI behavior