README.md (8478B)
1 # lanyard 2 3 AI-driven badge OSINT, credential harvesting, and calibrated CR80 card cloning for physical red teams. 4 5 <p align="center"> 6 <img src="assets/dashboard-demo.png" alt="Lanyard Badge Intelligence Dossier" width="100%"> 7 </p> 8 9 ## Table of Contents 10 11 - [Description](#description) 12 - [Prerequisites](#prerequisites) 13 - [Installation](#installation) 14 - [Standard Installation (pip)](#standard-installation-pip) 15 - [Alternative Installation (uv)](#alternative-installation-uv) 16 - [Configuration](#configuration) 17 - [LinkedIn Authentication](#linkedin-authentication) 18 - [Vision Provider Setup](#vision-provider-setup) 19 - [Usage](#usage) 20 - [1. Company Badge Hunt](#1-company-badge-hunt) 21 - [2. Local Directory Analysis](#2-local-directory-analysis) 22 - [3. Interactive Dossier Server](#3-interactive-dossier-server) 23 - [4. Exporting Reports](#4-exporting-reports) 24 - [Outputs](#outputs) 25 - [Supported Vision Models](#supported-vision-models) 26 - [License](#license) 27 28 --- 29 30 ## Description 31 32 During physical penetration tests and red team engagements, cloning employee access badges or creating visual counterfeits requires high-resolution references. Employees frequently upload photos of their badges on LinkedIn when starting a new job, receiving a promotion, or finishing an internship. 33 34 `lanyard` automates this collection pipeline: 35 36 1. Connects to LinkedIn via [Camoufox](https://github.com/daijro/camoufox) to bypass bot detection. 37 2. Searches company employee posts across multiple hiring and milestone angles. 38 3. Steps through multi-photo albums and carousels to catch hidden slide attachments. 39 4. Uses multimodal vision models to detect physical ID cards, extract cardholder details (names, roles, IDs), identify physical access markers (RFID chips, barcodes, magstripes), and locate card corners. 40 5. Applies a perspective homography transform to deskew the badge into flat, 300 DPI CR80 dimensions (85.6mm x 54.0mm) ready for direct PVC card printing. 41 6. Compiles all findings into an offline SQLite database, CSV, JSONL, and a local HTML inspection report. 42 43 --- 44 45 ## Prerequisites 46 47 - Linux or macOS (tested on Kali Linux and Debian/Ubuntu) 48 - Python 3.12+ 49 - Standard `pip` or `uv` 50 51 --- 52 53 ## Installation 54 55 Lanyard works out of the box in standard Python environments using `pip`. You do not need `uv` to install or run the tool. 56 57 ### Quick Setup (Automated) 58 59 Run the setup script to detect your Python environment, configure dependencies (using `uv` if present, or falling back to standard `venv` and `pip`), download [Camoufox](https://github.com/daijro/camoufox) browser binaries, and initialize local directories: 60 61 ```bash 62 git clone https://github.com/shehzade/lanyard.git 63 cd lanyard 64 ./setup.sh 65 ``` 66 67 ### Manual Installation (pip) 68 69 ```bash 70 git clone https://github.com/shehzade/lanyard.git 71 cd lanyard 72 python3 -m venv .venv 73 source .venv/bin/activate 74 pip install -e . 75 camoufox fetch 76 ``` 77 78 ### Manual Installation (uv) 79 80 ```bash 81 git clone https://github.com/shehzade/lanyard.git 82 cd lanyard 83 uv sync 84 uv run camoufox fetch 85 ``` 86 87 --- 88 89 ## Configuration 90 91 When working inside your activated virtual environment, execute commands directly with `lanyard <command>`. If you prefer using `uv` without manually activating the virtual environment, prefix any command with `uv run lanyard <command>`. 92 93 ### LinkedIn Authentication 94 95 To search LinkedIn, provide an existing session. Two methods are supported: 96 97 **Method 1: Import `li_at` cookie (Headless)** 98 99 Copy the `li_at` cookie from your browser and import it: 100 101 ```bash 102 lanyard cookie "AQEDAT..." 103 ``` 104 105 **Method 2: Interactive Browser Login** 106 107 Opens a browser window to log in manually. The resulting session profile is saved locally to `~/.lanyard/`: 108 109 ```bash 110 lanyard login 111 ``` 112 113 ### Vision Provider Setup 114 115 Lanyard supports Google Gemini, OpenAI, Anthropic, Ollama, and OpenRouter. You can configure credentials either by saving them to your local config (`~/.lanyard/config.json`) using `lanyard config` or by setting standard environment variables. 116 117 #### Google Gemini 118 119 ```bash 120 lanyard config --provider gemini --gemini-key "AIzaSy..." --gemini-model "gemini-3.8-flash" 121 # Or: export GEMINI_API_KEY="AIzaSy..." 122 ``` 123 124 #### OpenAI 125 126 ```bash 127 lanyard config --provider openai --openai-key "sk-..." --openai-model "gpt-4o" 128 # Or: export OPENAI_API_KEY="sk-..." 129 ``` 130 131 #### Anthropic 132 133 ```bash 134 lanyard config --provider anthropic --anthropic-key "sk-ant-..." --anthropic-model "claude-3-7-sonnet-20250219" 135 # Or: export ANTHROPIC_API_KEY="sk-ant-..." 136 ``` 137 138 #### Ollama (Local / Air-Gapped) 139 140 ```bash 141 ollama pull qwen2.5vl 142 lanyard config --provider ollama --ollama-model "qwen2.5vl" --ollama-base "http://localhost:11434" 143 # Or: export OLLAMA_BASE_URL="http://localhost:11434" 144 ``` 145 146 #### OpenRouter 147 148 ```bash 149 lanyard config --provider openrouter --openrouter-key "sk-or-..." --openrouter-model "qwen/qwen-2.5-vl-72b-instruct" 150 # Or: export OPENROUTER_API_KEY="sk-or-..." 151 ``` 152 153 Inspect active configuration at any time: 154 155 ```bash 156 lanyard config --show 157 ``` 158 159 --- 160 161 ## Usage 162 163 ### 1. Company Badge Hunt 164 165 Target an organization and scrape public employee posts: 166 167 ```bash 168 lanyard hunt -c "Acme Corp" --depth 5 169 ``` 170 171 Options: 172 - `-c, --company`: Target organization name. 173 - `-d, --depth`: Number of scroll pages to evaluate per query angle (default: 10). 174 - `-t, --threads`: Concurrent worker threads for vision analysis (default: 4). 175 - `-o, --output`: Directory to store media and database (default: `./lanyard_output`). 176 - `-P, --provider`: Override active vision backend (`gemini`, `openai`, `anthropic`, `ollama`, `openrouter`). 177 - `-m, --model`: Override model name for this scan. 178 179 Example targeting specific depth and output directory: 180 ```bash 181 lanyard hunt -c "Acme Corp" --depth 12 --threads 4 -o ./acme_results 182 ``` 183 184 ### 2. Local Directory Analysis 185 186 Analyze an existing directory of photos directly without opening a browser: 187 188 ```bash 189 lanyard analyze-dir ./photos/ -o ./photos_results --threads 4 190 ``` 191 192 ### 3. Interactive Dossier Server 193 194 Serve the web gallery locally: 195 196 ```bash 197 lanyard serve -o ./acme_results -p 8088 198 ``` 199 200 Open `http://127.0.0.1:8088/report.html` in your browser. The gallery includes: 201 - Side-by-side view of original photos and cropped cards. 202 - CR80 perspective toggle for viewing the flat PVC badge layout. 203 - Pan and zoom controls for reading dense text, barcodes, and chip serials. 204 - Filter controls for badge type (employee, contractor, visitor). 205 206 #### Calibrated CR80 Card Reconstruction (300 DPI) 207 208 Lanyard detects badge boundary corners and applies a perspective homography matrix to output flat, print-ready PVC cards (85.6mm × 54.0mm): 209 210 | Shi Choong (Intel) | Wendy Ngoh (Intel) | Kosta Briger (Intel) | 211 | :---: | :---: | :---: | 212 | <img src="assets/cr80-shi-choong.png" width="280" alt="Shi Choong CR80 Badge"> | <img src="assets/cr80-wendy-ngoh.png" width="280" alt="Wendy Ngoh CR80 Badge"> | <img src="assets/cr80-kosta-briger.png" width="280" alt="Kosta Briger CR80 Badge"> | 213 | *Extracted: Name, Photo, Corporate Branding* | *Extracted: Name, Photo, RFID Geometry* | *Extracted: Dual-Language Typography, Badge Reel* | 214 215 ### 4. Exporting Reports 216 217 Regenerate HTML, CSV, and JSONL deliverables from an existing `lanyard.db`: 218 219 ```bash 220 lanyard report -o ./acme_results 221 ``` 222 223 --- 224 225 ## Outputs 226 227 All collected assets are organized inside the specified output directory: 228 229 ```text 230 output_dir/ 231 ├── cr80/ # Deskewed 300 DPI PVC cards (PNG and SVG) 232 ├── crops/ # Bounding box crops of identified badges 233 ├── originals/ # High-resolution uncompressed downloaded photos 234 ├── report.html # Standalone visual report gallery 235 ├── findings.csv # Tabular export for spreadsheet analysis 236 ├── findings.jsonl # JSONL stream of structured findings and coordinates 237 └── lanyard.db # SQLite database of images and detections 238 ``` 239 240 --- 241 242 ## Supported Vision Models 243 244 | Backend | Default Model | Notes | 245 | :--- | :--- | :--- | 246 | **Gemini** | `gemini-3.8-flash` | Fast inference, structured JSON output. | 247 | **OpenAI** | `gpt-4o` | Structured output via `json_schema` strict mode. | 248 | **Anthropic** | `claude-3-7-sonnet-20250219` | Tool-use schema enforcement. | 249 | **Ollama** | `qwen2.5vl` | Offline, local execution for air-gapped engagements. | 250 | **OpenRouter** | `qwen/qwen-2.5-vl-72b-instruct` | Cloud endpoint for open-weight models. | 251 252 --- 253 254 ## License 255 256 This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.