Compare commits
1 Commits
step35/875
...
fix/506
| Author | SHA1 | Date | |
|---|---|---|---|
|
c45110ba9b |
@@ -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.
|
||||
|
||||
@@ -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`).
|
||||
|
||||
@@ -27,7 +27,7 @@ p.write_text('\n'.join(lines) + '\n')
|
||||
PY
|
||||
systemctl restart hermes-ezra.service openclaw-ezra.service"
|
||||
|
||||
ssh root@67.205.155.108 "python3 - <<'PY'
|
||||
ssh root@167.99.126.228 "python3 - <<'PY'
|
||||
from pathlib import Path
|
||||
p = Path('/root/wizards/bezalel/home/.env')
|
||||
text = p.read_text() if p.exists() else ''
|
||||
@@ -42,4 +42,7 @@ p.write_text('\n'.join(lines) + '\n')
|
||||
PY
|
||||
systemctl restart hermes-bezalel.service"
|
||||
|
||||
# Note: Bezalel migrated to Allegro VPS (167.99.126.228) after original TestBed VPS
|
||||
# (67.205.155.108) became unreachable on 2026-04-04. See #506.
|
||||
|
||||
echo 'Wizard Telegram bot tokens installed and services restarted.'
|
||||
|
||||
@@ -7,7 +7,7 @@ Finish the last mile for Ezra and Bezalel entering the `Timmy Time` Telegram gro
|
||||
|
||||
Done:
|
||||
- Ezra house exists on `143.198.27.163`
|
||||
- Bezalel house exists on `67.205.155.108`
|
||||
- Bezalel house exists on `167.99.126.228` (shared with Allegro after TestBed VPS at 67.205.155.108 died 2026-04-04)
|
||||
- both Hermes API health endpoints answered locally
|
||||
- Timmy Time Telegram home channel is known:
|
||||
- group id: `-1003664764329`
|
||||
@@ -71,7 +71,7 @@ After creation, add both bots to the `Timmy Time` group and grant permission to
|
||||
- openclaw sidecar: `openclaw-ezra.service`
|
||||
|
||||
### Bezalel host
|
||||
- host: `67.205.155.108`
|
||||
- host: `167.99.126.228` (shared with Allegro; original TestBed VPS 67.205.155.108 dead since 2026-04-04)
|
||||
- hermes home: `/root/wizards/bezalel/home/.env`
|
||||
- service: `hermes-bezalel.service`
|
||||
|
||||
@@ -102,9 +102,11 @@ ssh root@143.198.27.163 'systemctl restart hermes-ezra.service openclaw-ezra.ser
|
||||
|
||||
### Bezalel
|
||||
```bash
|
||||
ssh root@67.205.155.108 'systemctl restart hermes-bezalel.service'
|
||||
ssh root@167.99.126.228 'systemctl restart hermes-bezalel.service'
|
||||
```
|
||||
|
||||
> Note: Bezalel shares the Allegro VPS after the original TestBed VPS (67.205.155.108) became unreachable on 2026-04-04. See #506.
|
||||
|
||||
## Acceptance proof
|
||||
|
||||
The cutover is complete only when all are true:
|
||||
|
||||
@@ -10,9 +10,12 @@ This document records the first concrete house layout for Ezra and Bezalel.
|
||||
- Role: repo / Gitea / architecture wizard house
|
||||
|
||||
### Bezalel host
|
||||
- VPS: TestBed
|
||||
- Public IP: `67.205.155.108`
|
||||
- VPS: TestBed (DEPRECATED — original VPS at 67.205.155.108 unreachable since 2026-04-04)
|
||||
- Public IP: `167.99.126.228` (shared with Allegro VPS)
|
||||
- Role: forge / test / optimization wizard house
|
||||
- Migration: Bezalel services colocated with Allegro after TestBed VPS failure
|
||||
|
||||
> Note: The original TestBed VPS (67.205.155.108) is dead. Bezalel was migrated to share the Allegro VPS (167.99.126.228) to restore CI testbed and wizard house functionality. See #506.
|
||||
|
||||
## Directory layout
|
||||
|
||||
|
||||
@@ -351,7 +351,7 @@ houses:
|
||||
role: archivist
|
||||
|
||||
bezalel:
|
||||
endpoint: http://67.205.155.108:8643
|
||||
endpoint: http://167.99.126.228:8643 # Shared with Allegro after TestBed VPS death (was 67.205.155.108)
|
||||
role: artificer
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user