# abdullahjadoon34/access-anomaly-analyzer architecture

> Architecture diagram of the GitHub repository abdullahjadoon34/access-anomaly-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullahjadoon34/access-anomaly-analyzer
- Repository: https://github.com/abdullahjadoon34/access-anomaly-analyzer

## Overview

#### 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`](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py) (Streamlit Runtime), [`access_logs.csv`](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/access_logs.csv) (Access Log CSV), [`requirements.txt`](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/requirements.txt) (Python Dependencies), [`RUN_INSTRUCTIONS.txt`](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/RUN_INSTRUCTIONS.txt) (Run Instructions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local Streamlit App"]
  node_streamlit{{"Streamlit Runtime<br/>ui runtime<br/>[app.py]"}}
  node_app["Application Flow<br/>python app<br/>[app.py]"]
  node_rules["Detection Rules<br/>rule engine<br/>[app.py]"]
  node_findings["Verified Findings<br/>trusted findings<br/>[app.py]"]
  node_risk["Risk Prioritization<br/>triage layer<br/>[app.py]"]
  node_views["Incident Views<br/>Streamlit views<br/>[app.py]"]
  node_requirements["Python Dependencies<br/>dependency manifest<br/>[requirements.txt]"]
  node_runbook["Run Instructions<br/>operator guide"]
end

subgraph group_data["Demo Data"]
  node_csv["Access Log CSV<br/>input contract<br/>[access_logs.csv]"]
  node_generator["Dataset Generator<br/>python generator<br/>[gen_data.py]"]
end

subgraph group_ai["Optional AI"]
  node_narrative["Narrative Generator<br/>optional feature<br/>[app.py]"]
  node_anthropic{{"Claude / Anthropic<br/>external LLM"}}
end

node_user(("SOC Analyst<br/>user"))
node_readme["Project Documentation<br/>[README.md]"]

node_user -->|"launches and interacts with"| node_streamlit
node_runbook -.->|"documents launch"| node_streamlit
node_requirements -.->|"provides dependencies"| node_streamlit
node_streamlit -->|"runs"| node_app
node_generator -->|"generates"| node_csv
node_csv -->|"loads events"| node_app
node_app -->|"evaluates"| node_rules
node_rules -->|"emits suspicious events"| node_findings
node_findings -->|"prioritizes"| node_risk
node_risk -->|"renders guidance"| node_views
node_views -->|"presents triage"| node_user
node_findings -->|"grounds input"| node_narrative
node_anthropic -.->|"generates when configured"| node_narrative
node_narrative -->|"adds incident brief"| node_views
node_readme -.->|"documents AI behavior"| node_narrative

click node_streamlit "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_app "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_csv "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/access_logs.csv"
click node_generator "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/gen_data.py"
click node_rules "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_findings "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_risk "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_views "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_narrative "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py"
click node_requirements "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/requirements.txt"
click node_runbook "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/RUN_INSTRUCTIONS.txt"
click node_readme "https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_app,node_rules,node_findings,node_risk,node_views,node_requirements,node_runbook toneBlue
class node_csv,node_generator toneAmber
class node_narrative,node_anthropic toneMint
class node_user,node_readme toneNeutral
```

## Components

### Local Streamlit App

Offline-first analysis runs in one Python process.

- [Streamlit Runtime](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): ui runtime · Launches and renders the local application. · `app.py`
- [Application Flow](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): python app · Coordinates loading, detection, prioritization, views, and narratives. · `app.py`
- [Detection Rules](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): rule engine · Detects impossible travel, brute force, misuse, escalation, and anonymizer activity. · `app.py`
- [Verified Findings](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): trusted findings · Only rule-passing events may feed AI output. · `app.py`
- [Risk Prioritization](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): triage layer · Structures and prioritizes findings with response guidance. · `app.py`
- [Incident Views](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): Streamlit views · Presents risk panels and incident-oriented analyst views. · `app.py`
- [Python Dependencies](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/requirements.txt): dependency manifest · `requirements.txt`
- [Run Instructions](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/RUN_INSTRUCTIONS.txt): operator guide · `RUN_INSTRUCTIONS.txt`

### Demo Data

Repeatable synthetic authentication-log input.

- [Access Log CSV](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/access_logs.csv): input contract · 308 synthetic events including planted incidents. · `access_logs.csv`
- [Dataset Generator](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/gen_data.py): python generator · Produces reproducible demo input with a fixed seed. · `gen_data.py`

### Optional AI

Narrative generation consumes verified findings only.

- [Narrative Generator](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/app.py): optional feature · Uses a built-in demo brief when external AI is unavailable. · `app.py`
- **Claude / Anthropic**: external LLM · Enabled only when ANTHROPIC_API_KEY is configured.

### Other components

- **SOC Analyst**: user
- [Project Documentation](https://github.com/abdullahjadoon34/access-anomaly-analyzer/blob/main/README.md): documentation · `README.md`

## Connections

- 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