Compare commits
1 Commits
step35/875
...
fix/513
| Author | SHA1 | Date | |
|---|---|---|---|
|
89de5b2c69 |
@@ -1,126 +0,0 @@
|
||||
# Username OSINT Operator Policy
|
||||
|
||||
**Effective**: 2026-04-26
|
||||
**Applies to**: Username enumeration results produced by `maigret` / `socialscan` / `sherlock`
|
||||
**Exempt**: Manual human social-engineering (this policy covers automated tool output only)
|
||||
**Related**: timmy-home#875, `research/username-osint/decision-memo.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This policy governs how username OSINT findings are stored, interpreted, and acted upon within Timmy. It exists to prevent:
|
||||
- Treating heuristic matches as identity proof
|
||||
- Accumulating stale or misattributed data in durable storage
|
||||
- Acting on findings without human review and source validation
|
||||
|
||||
---
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This policy applies when any of the following tools are invoked:
|
||||
- `maigret` (primary)
|
||||
- `socialscan` (secondary)
|
||||
- `sherlock` (archived/reference-only)
|
||||
|
||||
Tools may be invoked:
|
||||
- via `hermes` session with explicit instruction
|
||||
- via standalone script in `scripts/username-osint/`
|
||||
- via ad-hoc terminal command (operator discretion)
|
||||
|
||||
---
|
||||
|
||||
## 3. Storage boundaries
|
||||
|
||||
### 3.1 File locations
|
||||
- **Research packets** (bounded study artifacts) → `research/username-osint/`
|
||||
- **Single-use findings** (ad-hoc runs not tied to a study) → `/tmp/` (ephemeral)
|
||||
- **Canonical knowledge** (vetted, review-approved) → `knowledge/username-handles/` (if such a directory exists; otherwise never write to durable knowledge store)
|
||||
|
||||
### 3.2 Naming & provenance envelope
|
||||
Every saved artifact (to `research/username-osint/` or any durable location) **must** include a YAML frontmatter block:
|
||||
|
||||
```yaml
|
||||
---
|
||||
date: YYYY-MM-DD
|
||||
tool: maigret|socialscan|sherlock # exact command line used
|
||||
tool_version: <pip show version output>
|
||||
username_pattern: <pattern or list used; e.g. "alice,bob,charlie" or "@corp-employees.txt">
|
||||
sample_platforms: [github,twitter,instagram,reddit] # or "full-site-list"
|
||||
status: draft|review|approved|rejected
|
||||
reviewer: <hermes username or empty if unreviewed>
|
||||
provenance_notes: |
|
||||
Free-text notes about rate limits, VPN usage, time-of-day, or other context
|
||||
that affects reproducibility.
|
||||
---
|
||||
```
|
||||
|
||||
The frontmatter is followed by the tool's raw JSON output (preserved verbatim) plus an optional human summary.
|
||||
|
||||
---
|
||||
|
||||
## 4. Invocation rules
|
||||
|
||||
| Invocation type | Allowed | Conditions |
|
||||
|---|---|---|
|
||||
| **Explicit Hermes command** | ✅ | User must name the tool and sample set explicitly in the session |
|
||||
| **Automated pipeline** | ⚠️ | Must include `--json` flag and write to `research/username-osint/` with provenance frontmatter |
|
||||
| **Blind/autonomous discovery** | ❌ | Agent may NOT autonomously decide to run username enumeration |
|
||||
|
||||
**No silent runs**. Every invocation must be traceable to a user message or logged pipeline step.
|
||||
|
||||
---
|
||||
|
||||
## 5. Interpretation guardrails
|
||||
|
||||
### 5.1 Language conventions (what you CAN say)
|
||||
- ✅ "Handle `alice` is found on GitHub (HTTP 200)"
|
||||
- ✅ "Platform presence detected for `alice` on 4 of 4 checked services"
|
||||
- ✅ "No public handle matches were found in the sample set"
|
||||
|
||||
### 5.2 Prohibited language (what you CANNOT say)
|
||||
- ❌ "`alice` is the identity of the target"
|
||||
- ❌ "This proves `alice` owns these accounts"
|
||||
- ❌ "These accounts belong to the subject"
|
||||
- ❌ "We have identified the person behind handle X"
|
||||
|
||||
**Rationale**: HTTP presence ≠ identity ownership. Platform migration, shared devices, and impersonation are common. These tools detect *availability of a public handle*, not *ownership of an identity*.
|
||||
|
||||
---
|
||||
|
||||
## 6. Review & retention
|
||||
|
||||
### 6.1 Review requirement
|
||||
Any artifact promoted from `research/username-osint/` to `knowledge/` (if such exists) **must** be reviewed by a human operator. Review checklist:
|
||||
- [ ] Source tool version recorded in frontmatter
|
||||
- [ ] False-positive spot-check performed (≥10% of found handles manually verified)
|
||||
- [ ] Implausible matches flagged (e.g., handles that are 10+ years old but target is known to be <5)
|
||||
- [ ] Storage location confirmed appropriate (research vs knowledge)
|
||||
|
||||
### 6.2 Retention & deletion
|
||||
- **Research artifacts**: Retained indefinitely (they are dated study packets)
|
||||
- **Single-use findings** in `/tmp/`: Deleted after 7 days by cron job (`scripts/cleanup_tmp_artifacts.sh`)
|
||||
- Stale artifacts without `status: approved` after 90 days are **archived** (moved to `archive/`), not deleted
|
||||
|
||||
---
|
||||
|
||||
## 7. Audit trail
|
||||
|
||||
All tool invocations that write to durable storage **must** log to `~/.timmy/logs/username-osint.log` with:
|
||||
```
|
||||
YYYY-MM-DD HH:MM:SS | tool=<tool> | usernames=<count> | platforms=<list> | output=<path> | reviewer=<name or "unreviewed">
|
||||
```
|
||||
|
||||
This enables traceability from any stored JSON back to the exact run.
|
||||
|
||||
---
|
||||
|
||||
## 8. Exceptions
|
||||
|
||||
Requests for exception to this policy require:
|
||||
1. A written justification in the research artifact's frontmatter (`provenance_notes`)
|
||||
2. Human reviewer sign-off in the `reviewer` field
|
||||
3. Explicit `status: approved` designation
|
||||
|
||||
No exceptions are granted for autonomous or unattended runs.
|
||||
|
||||
@@ -1059,6 +1059,46 @@ class GameEngine:
|
||||
self.log("It will always pulse. That much you know.")
|
||||
self.log("")
|
||||
self.world.save()
|
||||
|
||||
def _bridge_is_hazardous(self):
|
||||
bridge = self.world.rooms["Bridge"]
|
||||
return bool(
|
||||
self.world.state.get("bridge_flooding")
|
||||
or bridge.get("weather") == "rain"
|
||||
or bridge.get("rain_ticks", 0) > 0
|
||||
)
|
||||
|
||||
def _bridge_crossing_extra_cost(self, current_room, dest):
|
||||
if "Bridge" not in (current_room, dest):
|
||||
return 0
|
||||
return 2 if self._bridge_is_hazardous() else 0
|
||||
|
||||
def _event_dialogue(self, char_name, room_name):
|
||||
if char_name == "Bezalel" and room_name == "Forge":
|
||||
if self.world.rooms["Forge"]["fire"] == "cold":
|
||||
return random.choice([
|
||||
"The forge is cold. We cannot work until the fire lives again.",
|
||||
"No forging now. The hearth is dead cold.",
|
||||
])
|
||||
if self.world.state.get("forge_fire_dying"):
|
||||
return random.choice([
|
||||
"The fire is dying. Tend it before the forge goes dark.",
|
||||
"The forge is losing heat. Help me keep it alive.",
|
||||
])
|
||||
|
||||
if char_name == "Ezra" and room_name == "Tower" and self.world.state.get("tower_power_low"):
|
||||
return random.choice([
|
||||
"The Tower power is too low. The servers won't hold a clean study right now.",
|
||||
"The LED is flickering. We need steady power before the Tower can be read properly.",
|
||||
])
|
||||
|
||||
if char_name in {"Marcus", "Allegro"} and room_name == "Bridge" and self._bridge_is_hazardous():
|
||||
return random.choice([
|
||||
"The Bridge is slick with rain. Cross carefully or wait it out.",
|
||||
"This rain changes the Bridge. Don't treat it like dry stone.",
|
||||
])
|
||||
|
||||
return None
|
||||
|
||||
def log(self, message):
|
||||
"""Add to Timmy's log."""
|
||||
@@ -1094,6 +1134,7 @@ class GameEngine:
|
||||
}
|
||||
|
||||
# Process Timmy's action
|
||||
room_name = self.world.characters["Timmy"]["room"]
|
||||
timmy_energy = self.world.characters["Timmy"]["energy"]
|
||||
|
||||
# Energy constraint checks
|
||||
@@ -1156,8 +1197,17 @@ class GameEngine:
|
||||
|
||||
if direction in connections:
|
||||
dest = connections[direction]
|
||||
bridge_extra_cost = self._bridge_crossing_extra_cost(current_room, dest)
|
||||
move_cost = 1 + bridge_extra_cost
|
||||
if self.world.characters["Timmy"]["energy"] < move_cost:
|
||||
scene["log"].append("The rain makes the Bridge too costly to cross right now. Rest first.")
|
||||
scene["room_desc"] = self.world.get_room_desc(current_room, "Timmy")
|
||||
here = [n for n in self.world.characters if self.world.characters[n]["room"] == current_room and n != "Timmy"]
|
||||
scene["here"] = here
|
||||
return scene
|
||||
|
||||
self.world.characters["Timmy"]["room"] = dest
|
||||
self.world.characters["Timmy"]["energy"] -= 1
|
||||
self.world.characters["Timmy"]["energy"] -= move_cost
|
||||
|
||||
scene["log"].append(f"You move {direction} to The {dest}.")
|
||||
scene["timmy_room"] = dest
|
||||
@@ -1165,6 +1215,8 @@ class GameEngine:
|
||||
# Check for rain on bridge
|
||||
if dest == "Bridge" and self.world.rooms["Bridge"]["weather"] == "rain":
|
||||
scene["world_events"].append("Rain mists on the dark water below. The railing is slick.")
|
||||
if bridge_extra_cost:
|
||||
scene["log"].append("Rain turns the Bridge crossing into work. You brace against the slick stone. (-2 extra energy)")
|
||||
|
||||
# Check trust changes for arrival
|
||||
here = [n for n in self.world.characters if self.world.characters[n]["room"] == dest and n != "Timmy"]
|
||||
@@ -1310,25 +1362,69 @@ class GameEngine:
|
||||
|
||||
elif timmy_action == "write_rule":
|
||||
if self.world.characters["Timmy"]["room"] == "Tower":
|
||||
rules = [
|
||||
f"Rule #{self.world.tick}: The room remembers those who enter it.",
|
||||
f"Rule #{self.world.tick}: A man in the dark needs to know someone is in the room.",
|
||||
f"Rule #{self.world.tick}: The forge does not care about your schedule.",
|
||||
f"Rule #{self.world.tick}: Every footprint on the stone means someone made it here.",
|
||||
f"Rule #{self.world.tick}: The bridge does not judge. It only carries.",
|
||||
f"Rule #{self.world.tick}: A seed planted in patience grows in time.",
|
||||
f"Rule #{self.world.tick}: What is carved in wood outlasts what is said in anger.",
|
||||
f"Rule #{self.world.tick}: The garden grows whether anyone watches or not.",
|
||||
f"Rule #{self.world.tick}: Trust is built one tick at a time.",
|
||||
f"Rule #{self.world.tick}: The fire remembers who tended it.",
|
||||
]
|
||||
new_rule = random.choice(rules)
|
||||
self.world.rooms["Tower"]["messages"].append(new_rule)
|
||||
self.world.characters["Timmy"]["energy"] -= 1
|
||||
scene["log"].append(f"You write on the Tower whiteboard: \"{new_rule}\"")
|
||||
if self.world.state.get("tower_power_low"):
|
||||
scene["world_events"].append("The Tower power is too low. The LED flickers over the whiteboard.")
|
||||
scene["log"].append("The power is too low to write a new rule.")
|
||||
else:
|
||||
rules = [
|
||||
f"Rule #{self.world.tick}: The room remembers those who enter it.",
|
||||
f"Rule #{self.world.tick}: A man in the dark needs to know someone is in the room.",
|
||||
f"Rule #{self.world.tick}: The forge does not care about your schedule.",
|
||||
f"Rule #{self.world.tick}: Every footprint on the stone means someone made it here.",
|
||||
f"Rule #{self.world.tick}: The bridge does not judge. It only carries.",
|
||||
f"Rule #{self.world.tick}: A seed planted in patience grows in time.",
|
||||
f"Rule #{self.world.tick}: What is carved in wood outlasts what is said in anger.",
|
||||
f"Rule #{self.world.tick}: The garden grows whether anyone watches or not.",
|
||||
f"Rule #{self.world.tick}: Trust is built one tick at a time.",
|
||||
f"Rule #{self.world.tick}: The fire remembers who tended it.",
|
||||
]
|
||||
new_rule = random.choice(rules)
|
||||
self.world.rooms["Tower"]["messages"].append(new_rule)
|
||||
self.world.characters["Timmy"]["energy"] -= 1
|
||||
scene["log"].append(f"You write on the Tower whiteboard: \"{new_rule}\"")
|
||||
else:
|
||||
scene["log"].append("You are not in the Tower.")
|
||||
|
||||
elif timmy_action == "study":
|
||||
if self.world.characters["Timmy"]["room"] == "Tower":
|
||||
if self.world.state.get("tower_power_low"):
|
||||
scene["world_events"].append("The Tower power is too low. The servers stutter in weak light.")
|
||||
scene["log"].append("The power is too low to study the servers.")
|
||||
else:
|
||||
insights = [
|
||||
"You study the server rhythm until the pulse resolves into something readable.",
|
||||
"You trace the signal paths and feel the Tower settle into focus.",
|
||||
"You study the green LED and the server racks until the pattern becomes clear.",
|
||||
]
|
||||
insight = random.choice(insights)
|
||||
self.world.characters["Timmy"]["energy"] -= 1
|
||||
self.world.characters["Timmy"]["memories"].append(insight)
|
||||
scene["log"].append(insight)
|
||||
scene["world_events"].append("The Tower answers with a steady hum.")
|
||||
else:
|
||||
scene["log"].append("You are not in the Tower.")
|
||||
|
||||
elif timmy_action == "forge":
|
||||
if self.world.characters["Timmy"]["room"] == "Forge":
|
||||
forge_fire = self.world.rooms["Forge"]["fire"]
|
||||
if forge_fire == "cold":
|
||||
scene["world_events"].append("The forge is cold. No metal will take shape here yet.")
|
||||
scene["log"].append("The forge is cold. Tend the fire before you try to forge.")
|
||||
else:
|
||||
forged_items = [
|
||||
f"bridge nail #{self.world.tick}",
|
||||
f"tower key blank #{self.world.tick}",
|
||||
f"garden trowel #{self.world.tick}",
|
||||
]
|
||||
forged_item = random.choice(forged_items)
|
||||
self.world.rooms["Forge"]["forged_items"].append(forged_item)
|
||||
self.world.characters["Timmy"]["energy"] -= 2
|
||||
self.world.state["items_crafted"] += 1
|
||||
scene["log"].append(f"You forge {forged_item} at the anvil.")
|
||||
scene["world_events"].append("The anvil rings and the hearth answers.")
|
||||
else:
|
||||
scene["log"].append("You are not in the Forge.")
|
||||
|
||||
elif timmy_action == "carve":
|
||||
if self.world.characters["Timmy"]["room"] == "Bridge":
|
||||
carvings = [
|
||||
@@ -1414,7 +1510,11 @@ class GameEngine:
|
||||
speech_chance = 0.20
|
||||
|
||||
if random.random() < speech_chance:
|
||||
if char_name == "Marcus":
|
||||
event_line = self._event_dialogue(char_name, room_name)
|
||||
if event_line:
|
||||
self.world.characters[char_name]["spoken"].append(event_line)
|
||||
scene["log"].append(f"{char_name} says: \"{event_line}\"")
|
||||
elif char_name == "Marcus":
|
||||
marcus_pool = self.DIALOGUES["Marcus"].get(phase, self.DIALOGUES["Marcus"]["quietus"])
|
||||
line = random.choice(marcus_pool)
|
||||
self.world.characters[char_name]["spoken"].append(line)
|
||||
|
||||
@@ -1,107 +0,0 @@
|
||||
# Username OSINT Study — Decision Memo
|
||||
|
||||
**Date**: 2026-04-26
|
||||
**Study artifact**: `research/username-osint/tool-comparison.md`
|
||||
**Parent issue**: timmy-home#875
|
||||
**Status**: Complete — Recommendation Adopted
|
||||
|
||||
---
|
||||
|
||||
## Problem statement
|
||||
|
||||
Sherlock is currently the go-to username enumeration tool in Timmy workflows, but it is:
|
||||
- Slow (sequential requests)
|
||||
- Infrequently maintained
|
||||
- Broad but shallow in site coverage definition
|
||||
|
||||
We need to determine whether to:
|
||||
1. Stay with Sherlock
|
||||
2. Switch to Maigret
|
||||
3. Switch to Socialscan
|
||||
4. Adopt a layered stack (tool per use-case)
|
||||
5. Continue watching the ecosystem
|
||||
|
||||
---
|
||||
|
||||
## Method
|
||||
|
||||
Bounded sample set:
|
||||
- **Usernames**: `alice`, `bob`, `charlie`, `dave`, `eve` (common test handles)
|
||||
- **Platforms**: GitHub, Twitter/X, Instagram, Reddit
|
||||
- **Metrics collected**:
|
||||
- Install steps / friction
|
||||
- Total wall-clock time
|
||||
- Number of matches reported
|
||||
- False-positive indicators (404 pages served as 200, rate-limit gate pages)
|
||||
- Output format machine-readability
|
||||
- Output file size on disk
|
||||
|
||||
All tools run locally on macOS 14 (Apple Silicon) with Python 3.11. No API keys used; only public scrape.
|
||||
|
||||
Reference: `research/username-osint/tool-comparison.md` provides the full matrix.
|
||||
|
||||
---
|
||||
|
||||
## Findings (excerpt)
|
||||
|
||||
| Tool | Runtime | Matches | False positives | Install size |
|
||||
|---|---|---|---|---|
|
||||
| Sherlock | 45 s | 11 | 2 (GitHub 200-for-404) | ~15 MB |
|
||||
| Maigret | 12 s | 12 | 0 | ~8 MB |
|
||||
| Socialscan | 3 s | 9 | 0 | ~1 MB |
|
||||
|
||||
**Coverage**: Maigret's site list is ~2.5× larger than Sherlock's and ~8× larger than Socialscan's.
|
||||
|
||||
**Accuracy**: Maigret and Socialscan correctly classified GitHub vacancies; Sherlock treated GitHub's custom 404-with-recommendations page (HTTP 200) as a profile hit.
|
||||
|
||||
**Maintenance velocity**: Maigret merged 47 PRs in the last 90 days; Sherlock merged 6. Socialscan is stable with minimal churn.
|
||||
|
||||
**Output structure**: All three produce JSON, but schemas differ. Maigret's includes `response_time_ms` and explicit `status` values (`found`, `not_found`, ` unexplained_error`).
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Adopt Maigret as the primary username OSINT tool.** Keep Socialscan as a fast secondary option for CI/quick checks. Archive Sherlock as reference-only.
|
||||
|
||||
**Rationale**:
|
||||
- **Speed**: 3–4× faster than Sherlock with async HTTP (no additional hardware)
|
||||
- **Accuracy**: Better 404/not-found classification eliminates manual filtering
|
||||
- **Maintenance**: Active maintainer + clear contribution path
|
||||
- **Coverage**: Broadest site set without compromising signal-to-noise
|
||||
|
||||
---
|
||||
|
||||
## Implementation impact
|
||||
|
||||
- Replace `sherlock` invocations in any active scripts with `maigret`
|
||||
- No config changes required (no API keys anywhere)
|
||||
- Update output-parsing logic to Maigret's `status: found|not_found` fields (simpler than Sherlock's HTTP-status dance)
|
||||
- **Storage schema** changes: see `docs/USERNAME_OSINT_POLICY.md` for the provenance envelope
|
||||
|
||||
---
|
||||
|
||||
## Risks & mitigations
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|---|---|---|
|
||||
| Maigret site definitions drift / breakage over time | Medium | Monthly snapshot of site-data commit hash stored alongside each research artifact (provenance) |
|
||||
| False sense of precision from `status: found` | High | Language policy (see `USERNAME_OSINT_POLICY.md`) requires "handle found" not "identity confirmed" |
|
||||
| Rate-limiting by target platforms | Low | Maigret includes automatic adaptive delays; still ≤1 s between requests |
|
||||
|
||||
---
|
||||
|
||||
## Success criteria
|
||||
|
||||
- [x] Comparison matrix complete
|
||||
- [x] Decision recorded with clear rationale
|
||||
- [x] Operator policy written (see `docs/USERNAME_OSINT_POLICY.md`)
|
||||
- [x] Transition plan documented in this memo
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Full comparison: `research/username-osint/tool-comparison.md`
|
||||
- Operator policy: `docs/USERNAME_OSINT_POLICY.md`
|
||||
- Parent issue: timmy-home#875
|
||||
@@ -1,118 +0,0 @@
|
||||
# Username OSINT Tool Comparison — Sherlock / Maigret / Socialscan
|
||||
|
||||
**Date**: 2026-04-26
|
||||
**Research backlog item**: timmy-home#875
|
||||
**Sample set**: 5 usernames across 4 platforms (Twitter, Instagram, GitHub, Reddit)
|
||||
**Method**: Local-first install + direct CLI invocations; no API keys used
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
| Dimension | Sherlock | Maigret | Socialscan |
|
||||
|---|---|---|---|
|
||||
| **Install footprint** | `git clone + pip install -r requirements.txt` (pyproject.toml) | `pip install maigret` (single package) | `pip install socialscan` (single package) |
|
||||
| **Supported sites** | ~200 (site list in `sherlock/resources/data.json`) | ~500 (site list in `maigret/data.py`) | ~30 (primary focus: major social platforms) |
|
||||
| **Python requirement** | 3.8+ | 3.7+ | 3.6+ |
|
||||
| **Output formats** | JSON, CSV, HTML + terminal table | JSON, HTML (+ terminal coloured output) | Text table + JSON (via `--json`) |
|
||||
| **Sovereignty fit** | Local-only; no external deps beyond requests | Local-only; no external deps beyond aiohttp | Local-only; pure stdlib + requests |
|
||||
| **Maintenance state** | Last release 2024-03; PRs merged slowly | Last release 2025-12; active development | Last release 2024-05; minimal but stable |
|
||||
| **Async support** | Sequential (one site at a time) | Async (aiohttp — concurrent across sites) | Sequential but fast (small site list) |
|
||||
| **False-positive handling** | "Unavailable" ≠ "doesn't exist"; returns HTTP status codes | Metadata extraction + 404 detection; better error classification | Simple HTTP status check; limited nuance |
|
||||
| **Provenance metadata** | HTTP status + final URL + error code per-site | HTTP status + response time + platform-specific indicators | HTTP status code only |
|
||||
| **Niches** | Mature, well-documented, extensible site definitions | Broadest coverage, modern codebase, better performance | Fastest to run, smallest install, library-first design |
|
||||
|
||||
---
|
||||
|
||||
## Bounded sample run (same 5 usernames, 4 platforms)
|
||||
|
||||
| Tool | Total runtime | Found matches | False-positive flags | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Sherlock | ~45 s | 11 | 2 (GitHub 404 page returned 200) | Requires `--print-all` to see 404 vs 503 noise |
|
||||
| Maigret | ~12 s | 12 | 0 | Async concurrency + better 404 detection |
|
||||
| Socialscan | ~3 s | 9 | 0 | Limited site list misses niche platforms |
|
||||
|
||||
### Sample command used
|
||||
```bash
|
||||
# Sherlock (JSON report)
|
||||
python3 -m sherlock --output json --folder output/sherlock user1 user2 user3 user4 user5
|
||||
|
||||
# Maigret (HTML + JSON)
|
||||
maigret --html --json output/maigret user1 user2 user3 user4 user5
|
||||
|
||||
# Socialscan (JSON)
|
||||
socialscan --json user1 user2 user3 user4 user5 > output/socialscan.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Friction & maintenance
|
||||
|
||||
| Aspect | Sherlock | Maigret | Socialscan |
|
||||
|---|---|---|---|
|
||||
| **Install friction** | Clone + pip install -r; depends on `requests`, `colorama` | Single pip install; depends on `aiohttp`, `requests`, `beautifulsoup4` | Single pip install; depends only on `requests` |
|
||||
| **Update frequency** | Low — ~2 releases/year; PRs take weeks | High — monthly releases; active Discord | Low — stable, few changes needed |
|
||||
| **Site list hygiene** | JSON array; easy to edit manually but large file | Python dict; code-driven but harder to hand-edit | Hard-coded module list; easiest to read |
|
||||
| **Disk footprint** | ~15 MB (full repo with HTML report) | ~8 MB (pip-installed package) | ~1 MB (tiny package) |
|
||||
| **Configuration** | CLI flags only; no config file | CLI + optional `~/.config/maigret.json` | CLI only; zero config |
|
||||
|
||||
---
|
||||
|
||||
## Output structure comparison
|
||||
|
||||
**Sherlock** (`output/sherlock/<username>.json`):
|
||||
```json
|
||||
{
|
||||
"username": "user1",
|
||||
"found_on": {
|
||||
"GitHub": {"http_status": 200, "url": "https://github.com/user1"},
|
||||
"Twitter": {"http_status": 404, "error": "Not Found"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Maigret** (`output/maigret/<username>.json`):
|
||||
```json
|
||||
{
|
||||
"username": "user1",
|
||||
"sites": {
|
||||
"GitHub": {"status": "found", "url": "https://github.com/user1", "response_time_ms": 412},
|
||||
"Twitter": {"status": "not_found", "error": "404"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Socialscan** (stdout + `--json`):
|
||||
```json
|
||||
[{"platform":"github","username":"user1","available":false}, ...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sovereignty assessment
|
||||
|
||||
All three are **local-first, API-key-free** tools. None require cloud accounts. Network calls are direct to target platforms; no telemetry.
|
||||
|
||||
**Concern**: None of these tools expose request metadata (headers seen by target, IP rate-limit info) in a way that could be stored for reproducibility. We store only final status.
|
||||
|
||||
---
|
||||
|
||||
## Verdict matrix
|
||||
|
||||
| Use case | Recommended tool | Rationale |
|
||||
|---|---|---|
|
||||
| **Quick one-off check** | Socialscan | Smallest, fastest, minimal install |
|
||||
| **Broad coverage for many usernames** | Maigret | Async performance + best site list |
|
||||
| **Audit trail with per-site raw HTTP status** | Sherlock | Verbose JSON preserves raw 200/404/503 distinction |
|
||||
| **Low-end hardware / constrained environments** | Socialcan (typo intentional — it's small) | Tiny dependency tree |
|
||||
| **Future extensibility** | Maigret | Active maintainership + modular design |
|
||||
|
||||
---
|
||||
|
||||
## Next steps (non-blocking)
|
||||
|
||||
- Keep **Maigret** as the primary investigation tool (coverage + speed + maintenance).
|
||||
- Use **Socialscan** for smoke-checks in CI (speed).
|
||||
- **Sherlock** archived as reference; not retired but not actively used.
|
||||
- Consider writing a thin wrapper that normalizes output to a single provenance schema (see `docs/USERNAME_OSINT_POLICY.md`).
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
from importlib.util import module_from_spec, spec_from_file_location
|
||||
from pathlib import Path
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
@@ -66,6 +67,82 @@ class TestEvenniaLocalWorldGame(unittest.TestCase):
|
||||
self.assertIn("Ezra is already here.", result["log"])
|
||||
self.assertIn("The servers hum steady. The green LED pulses.", result["world_events"])
|
||||
|
||||
def test_bridge_rain_crossing_costs_extra_energy_and_warns(self):
|
||||
module = load_game_module()
|
||||
|
||||
dry_engine = module.GameEngine()
|
||||
dry_engine.start_new_game()
|
||||
dry_engine.world.update_world_state = lambda: None
|
||||
dry_engine.world.characters["Timmy"]["energy"] = 10
|
||||
dry_result = dry_engine.run_tick("move:south")
|
||||
dry_energy = dry_engine.world.characters["Timmy"]["energy"]
|
||||
|
||||
rainy_engine = module.GameEngine()
|
||||
rainy_engine.start_new_game()
|
||||
rainy_engine.world.update_world_state = lambda: None
|
||||
rainy_engine.world.characters["Timmy"]["energy"] = 10
|
||||
rainy_engine.world.rooms["Bridge"]["weather"] = "rain"
|
||||
rainy_engine.world.rooms["Bridge"]["rain_ticks"] = 3
|
||||
rainy_engine.world.state["bridge_flooding"] = True
|
||||
rainy_result = rainy_engine.run_tick("move:south")
|
||||
|
||||
self.assertEqual(rainy_engine.world.characters["Timmy"]["room"], "Bridge")
|
||||
self.assertLess(rainy_engine.world.characters["Timmy"]["energy"], dry_energy)
|
||||
self.assertTrue(
|
||||
any("bridge" in line.lower() and ("rain" in line.lower() or "slick" in line.lower()) for line in rainy_result["log"] + rainy_result["world_events"]),
|
||||
rainy_result,
|
||||
)
|
||||
|
||||
def test_tower_power_low_blocks_study_and_write_rule(self):
|
||||
module = load_game_module()
|
||||
engine = module.GameEngine()
|
||||
engine.start_new_game()
|
||||
engine.world.update_world_state = lambda: None
|
||||
engine.world.characters["Timmy"]["room"] = "Tower"
|
||||
engine.world.characters["Timmy"]["energy"] = 10
|
||||
engine.world.state["tower_power_low"] = True
|
||||
|
||||
rules_before = list(engine.world.rooms["Tower"]["messages"])
|
||||
study_result = engine.run_tick("study")
|
||||
self.assertEqual(engine.world.characters["Timmy"]["energy"], 10)
|
||||
self.assertTrue(
|
||||
any("power" in line.lower() and ("study" in line.lower() or "servers" in line.lower()) for line in study_result["log"] + study_result["world_events"]),
|
||||
study_result,
|
||||
)
|
||||
|
||||
write_result = engine.run_tick("write_rule")
|
||||
self.assertEqual(engine.world.rooms["Tower"]["messages"], rules_before)
|
||||
self.assertTrue(
|
||||
any("power" in line.lower() and ("write" in line.lower() or "whiteboard" in line.lower()) for line in write_result["log"] + write_result["world_events"]),
|
||||
write_result,
|
||||
)
|
||||
|
||||
def test_cold_forge_blocks_forge_action_and_bezalel_reacts(self):
|
||||
module = load_game_module()
|
||||
engine = module.GameEngine()
|
||||
engine.start_new_game()
|
||||
engine.world.update_world_state = lambda: None
|
||||
engine.npc_ai.make_choice = lambda _name: None
|
||||
engine.world.characters["Timmy"]["room"] = "Forge"
|
||||
engine.world.characters["Timmy"]["energy"] = 10
|
||||
engine.world.characters["Bezalel"]["room"] = "Forge"
|
||||
engine.world.rooms["Forge"]["fire"] = "cold"
|
||||
engine.world.state["forge_fire_dying"] = True
|
||||
forged_before = list(engine.world.rooms["Forge"]["forged_items"])
|
||||
|
||||
with patch.object(module.random, "random", return_value=0.0), patch.object(module.random, "choice", side_effect=lambda seq: seq[0]):
|
||||
result = engine.run_tick("forge")
|
||||
|
||||
self.assertEqual(engine.world.rooms["Forge"]["forged_items"], forged_before)
|
||||
self.assertTrue(
|
||||
any("forge" in line.lower() and ("cold" in line.lower() or "fire" in line.lower()) for line in result["log"] + result["world_events"]),
|
||||
result,
|
||||
)
|
||||
self.assertTrue(
|
||||
any(line.startswith("Bezalel says:") and ("fire" in line.lower() or "forge" in line.lower()) for line in result["log"]),
|
||||
result,
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
Reference in New Issue
Block a user