AegisML

AegisML is a lightweight, machine learning–powered tool for detecting anomalies in authentication logs using a hybrid approach:

• Deterministic rule engine – impossible travel, rare login hours, rapid failures → success, new device/location detection
• Per-user Isolation Forest models – identify behavioral outliers that rules can’t catch
• Human-readable explanations & severity scoring
• Markdown & JSON reports for both analysts and integrations.

---

📦 Installation

pip install -r requirements.txt

---

🚀 Quickstart

Run with the example config:

python -m AegisML.cli -c config.example.yaml

Reports will be generated in:

out/report.md
out/report.json

---

📂 Input Data

Provide a CSV or JSONL with at least:

username,timestamp,ip,result

Optional:

device_id,user_agent,latitude,longitude

• timestamp must be ISO-8601 (UTC recommended).
• If latitude/longitude are present, the agent can compute impossible travel.

---

🌍 GeoIP Database Setup

To enrich IPs with geolocation (country, city, coordinates), download the free MaxMind GeoLite2-City database:

1. Download the GeoLite2-City.mmdb file from https://github.com/P3TERX/GeoLite.mmdb.
2. Place it in the data/ folder (or the path specified in your config YAML).

Without this database, location-based rules (e.g., new location detection, impossible travel) will be disabled.

---

⚙️ Configuration

See config.example.yaml. Key settings:

• impossible_travel_speed_kmh (default 900)
• rare_hour_threshold_pct (default 2%)
• min_events_per_user_for_ml (default 15)
• ml_contamination (default 0.03)

---

🔍 How It Works

1. Loads data → parses timestamps → derives features like hour/day-of-week → computes distances/speeds (if lat/lon present).
2. Runs deterministic rules to flag obvious anomalies.
3. Trains per-user Isolation Forest models for statistical outliers.
4. Combines results into a severity score.
5. Outputs Markdown + JSON reports with human-readable explanations.

---

🛠 Extending

• Add new rules in AegisML/rules.py and include them in AegisML/agent.py.
• Add new reporters in AegisML/reporters/.
• Integrate with SIEM by replacing reporters/jsonout.py with a webhook or ticketing system sink.

---

🧪 Testing

Minimal example dataset in logins_data/logins.csv.
For better ML results, increase the number of rows.

---