{"id":50545031,"url":"https://github.com/byfranke/sheep-feeds-cli","last_synced_at":"2026-06-03T23:01:30.125Z","repository":{"id":361060643,"uuid":"1242603107","full_name":"byfranke/sheep-feeds-cli","owner":"byfranke","description":"Command-line client for the Sheep threat-intelligence feeds API at sheep.byfranke.com. Pulls curated feeds (CVEs, ransomware victims, IOCs, APT infrastructure, ICS/SCADA advisories, threat-intel articles) as JSON for use in SIEMs, SOAR playbooks, scripts and ad-hoc terminal queries.","archived":false,"fork":false,"pushed_at":"2026-05-29T02:43:52.000Z","size":87,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T04:21:32.519Z","etag":null,"topics":["cybersecurity","threat-intelligence","threatintel"],"latest_commit_sha":null,"homepage":"https://sheep.byfranke.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byfranke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T15:20:30.000Z","updated_at":"2026-05-29T02:43:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/byfranke/sheep-feeds-cli","commit_stats":null,"previous_names":["byfranke/sheep-feeds-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/byfranke/sheep-feeds-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-feeds-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-feeds-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-feeds-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-feeds-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byfranke","download_url":"https://codeload.github.com/byfranke/sheep-feeds-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-feeds-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33883102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cybersecurity","threat-intelligence","threatintel"],"created_at":"2026-06-03T23:01:29.558Z","updated_at":"2026-06-03T23:01:30.118Z","avatar_url":"https://github.com/byfranke.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sheep Feeds CLI\n\nCommand-line client for the **Sheep threat-intelligence feeds API** at\n[sheep.byfranke.com](https://sheep.byfranke.com). Pulls curated feeds\n(CVEs, ransomware victims, IOCs, APT infrastructure, ICS/SCADA\nadvisories, threat-intel articles) as JSON for use in SIEMs, SOAR\nplaybooks, scripts and ad-hoc terminal queries.\n\n```\nsheep-feeds list                      # list every feed with last update\nsheep-feeds latest cve --count 20     # 20 most recent CVE entries\nsheep-feeds get ransomware --since 2026-05-01 --json   # raw JSON\nsheep-feeds stats cve                 # per-feed statistics\nsheep-feeds summary                   # dashboard-style overview\nsheep-feeds plan                      # show your plan, quota and active token\n\n# Watch — local rules engine that pings you when feeds match\nsheep-feeds watch add nginx-high --feed cve --contains nginx --severity high --notify desktop\nsheep-feeds watch run --once          # one scan (cron / systemd timer)\nsheep-feeds watch run                 # loop in the foreground / inside a service\n```\n\n---\n\n## Why this exists\n\nThe same feeds the Sheep Discord bot broadcasts on `/feeds` and\n`/blackfeeds` are also exposed as a REST API. This CLI wraps that API\nso you can pipe the data straight into your tooling without writing a\nclient every time.\n\nSample uses we have shipped to customers:\n\n- **SIEM ingest:** cron job that calls\n  `sheep-feeds get cve --since \"$LAST\" --json | jq …` and pushes new\n  rows into Wazuh / Splunk / Elastic.\n- **SOAR playbooks:** workflow node (Tines, Shuffle, your own\n  Python worker, etc.) that polls\n  `sheep-feeds latest ransomware --count 50 --json` and filters by\n  country/sector before paging the incident team.\n- **Daily digest:** scheduled job (cron, Kubernetes CronJob, GitHub\n  Actions on a schedule) that runs `sheep-feeds summary` and prints\n  to a shared terminal in the SOC.\n- **Spot-check from terminal:** `sheep-feeds get cve --severity high`\n  to glance at the high-severity bucket before standup.\n\n---\n\n## Install\n\n### Quick\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/byfranke/sheep-feeds-cli/main/install.sh | bash\n```\n\nThe installer clones the repo into `~/.sheep-feeds-cli`, installs\ndependencies, drops a `sheep-feeds` symlink in `/usr/local/bin` (or\n`~/.local/bin` if that's not writable), and runs the interactive setup\nwizard.\n\n### Manual\n\n```bash\ngit clone https://github.com/byfranke/sheep-feeds-cli.git ~/.sheep-feeds-cli\ncd ~/.sheep-feeds-cli\npip install -r requirements.txt\npython3 setup.py\n```\n\n### Uninstall\n\n```bash\n~/.sheep-feeds-cli/uninstall.sh\n```\n\n---\n\n## Configure\n\nThe setup wizard (`setup.py`) does three things:\n\n1. Asks for your API token (starts with `shp_`).\n2. Encrypts it with a master password (PBKDF2-HMAC-SHA256, 600k iters)\n   in `~/.sheep-feeds-cli/config.ini` (mode 0600).\n3. Optionally installs `sheep-feeds` system-wide.\n\nYou enter the master password **once per terminal session** — the CLI\ncaches the decrypted token in a per-session file under `/tmp/` (mode\n0600, owner-only) so subsequent commands run without prompting.\n\n### Token resolution order\n\n```\n$SHEEP_API_TOKEN  (env var, highest priority — useful for CI/CD)\nsystem keyring     (when populated by setup.py and available)\nencrypted config   (config.ini decrypted with master password)\n--token \u003cvalue\u003e    (one-shot override, never persisted)\n```\n\nYou **don't need** the CLI to use keyring — setup.py only stores the\nencrypted blob in the config file by default. The keyring path is for\nnon-interactive workflows where typing a master password isn't viable.\n\n### Where to get a token\n\n- Sheep Plus / Sheep Pro / Sheep Pro Max — sign up at\n  [sheep.byfranke.com/pages/store](https://sheep.byfranke.com/pages/store),\n  token is emailed to you.\n- Black Sheep gift card — redeem on Discord with `/token`.\n\n---\n\n## Commands\n\n### `sheep-feeds list`\nList every feed and its last-update timestamp.\n\n### `sheep-feeds categories`\nGroup feeds by category.\n\n### `sheep-feeds summary`\nCompact, dashboard-style overview of all feeds with item counts and\nstatus. Useful for cron-driven monitoring.\n\n### `sheep-feeds get \u003cfeed_id\u003e` *(workhorse)*\nPulls items from a single feed.\n\nOptions:\n\n| Flag | Default | Notes |\n|---|---|---|\n| `--limit` | 50 | Max items per call (1-500). |\n| `--offset` | 0 | Pagination offset. |\n| `--last` | none | Time-window shortcut: `24h`, `3d`, `2w`, or aliases `today` / `yesterday` / `week` / `month`. Caps at 30 days (server retention). Mutually exclusive with `--since`. |\n| `--since` | none | ISO-8601 timestamp; items strictly after this. Use `--last` instead when you don't need to-the-second precision. |\n| `--severity` | none | Substring match (case-insensitive) on `severity`. |\n| `--category` | none | Substring match on `category`. |\n| `--json` | off | Print the raw API JSON instead of a table. |\n\nExamples:\n\n```bash\n# Everything from the last 24 hours\nsheep-feeds get cve --last 24h\n\n# Three days of ransomware leaks, as JSON ready to pipe into jq\nsheep-feeds get ransomware --last 3d --json | jq '.items[].title'\n\n# Last week of high-severity advisories\nsheep-feeds get cve --last week --severity high\n\n# Page 3 of ICS advisories (no time window)\nsheep-feeds get ics_scada --limit 25 --offset 50\n```\n\n### `sheep-feeds latest \u003cfeed_id\u003e`\nShortcut for the N newest items. Combine with `--last` to bound the\nsearch window before picking the freshest ones.\n\n```bash\nsheep-feeds latest cve --count 20\nsheep-feeds latest ioc_stream --count 5 --last 24h --json\n```\n\n### `sheep-feeds stats \u003cfeed_id\u003e`\nPer-feed statistics (counts by severity / category / source).\n\n### `sheep-feeds plan`\nShow your plan, status, period-end date, current-period token usage\nand any parallel tokens bound to the same email. Useful as a pre-flight\ncheck before scheduling a heavy ingest. Add `--json` for machine-readable\noutput.\n\n```bash\nsheep-feeds plan\nsheep-feeds plan --json | jq '.usage.tokens_remaining'\n```\n\n---\n\n## Watch — local alerts when feeds match\n\nWatch turns the CLI into a quiet sentinel: define rules against the\nfeeds you care about, leave the agent running, get a desktop or\nwebhook alert the moment something new matches.\n\nWatch consumes **zero AI tokens** — it only reads the feeds (already\nfree on every paid plan) and applies your rules locally.\n\n### Building rules\n\n```bash\n# CVEs that mention nginx, severity high\nsheep-feeds watch add nginx-high --feed cve --contains nginx --severity high --notify desktop\n\n# Anything ransomware-related from a specific actor, alert in Slack\nsheep-feeds watch add lockbit-radar --feed ransomware --contains lockbit \\\n    --notify \"https://hooks.slack.com/services/AAA/BBB/CCC\"\n\n# Critical items across every feed, two channels\nsheep-feeds watch add crit-fanout --feed '*' --severity critical \\\n    --notify desktop \\\n    --notify \"https://your-soar.example/sheep-hook\"\n\n# Regex on title + content\nsheep-feeds watch add cisco-asa --feed cve --regex \"cisco\\\\s+asa\" --notify desktop\n```\n\nRule fields:\n\n| Flag | Behaviour |\n|---|---|\n| `--feed \u003cid\u003e` | One of `cve`, `ransomware`, `threat_intel`, `apt_infrastructure`, `data_leak`, `ics_scada`, `kaspersky`, `ioc_stream`, `rss_news`, or `*` for every feed. |\n| `--severity` | One of `low`, `medium`, `high`, `critical`. Matched as case-insensitive substring against the item's severity. |\n| `--category` | Case-insensitive substring on the item's category. |\n| `--contains` | Case-insensitive substring on title + content. |\n| `--regex` | Python regex on title + content. Compiled once; input is capped to keep worst-case backtracking bounded. |\n| `--notify` | Repeat per channel. Values: `desktop` (libnotify / osascript / PowerShell BurntToast with a stderr fallback), or any `https://` webhook URL (POST JSON, 10s timeout, no retry). |\n\nAll match conditions on a rule are AND-ed. A rule with **none** of\nthe match filters is rejected (would fire on every item).\n\n### Listing and managing\n\n```bash\nsheep-feeds watch list                       # table\nsheep-feeds watch list --json                # machine-readable\nsheep-feeds watch pause nginx-high           # disable without removing\nsheep-feeds watch resume nginx-high\nsheep-feeds watch remove nginx-high          # delete the rule\n```\n\n### Inspecting hits\n\n```bash\nsheep-feeds watch hits                       # last 24h\nsheep-feeds watch hits --last 7d\nsheep-feeds watch hits --rule nginx-high\nsheep-feeds watch hits --json --limit 500    # SIEM ingest\n```\n\nHits are deduplicated by `(rule, feed, item_id)` — the same item never\nfires the same rule twice.\n\n### Running the watcher\n\n```bash\n# One-shot scan (perfect for cron / systemd timer)\nsheep-feeds watch run --once\n\n# Foreground loop — polls every N seconds (default 900)\nsheep-feeds watch run\nsheep-feeds watch run --interval 600         # every 10 minutes\n```\n\n### systemd user unit (recommended)\n\nDrop this in `~/.config/systemd/user/sheep-feeds-watch.service`:\n\n```ini\n[Unit]\nDescription=Sheep Feeds Watch\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=%h/.local/bin/sheep-feeds watch run --interval 900\nRestart=on-failure\nRestartSec=30s\n\n[Install]\nWantedBy=default.target\n```\n\n```bash\nsystemctl --user daemon-reload\nsystemctl --user enable --now sheep-feeds-watch\nsystemctl --user status sheep-feeds-watch\njournalctl --user -u sheep-feeds-watch -f\n```\n\n### cron alternative\n\n```cron\n*/15 * * * * /usr/local/bin/sheep-feeds watch run --once \u003e\u003e ~/.sheep-feeds-cli/watch/cron.log 2\u003e\u00261\n```\n\n### Where things live\n\n| Path | Content |\n|---|---|\n| `~/.sheep-feeds-cli/watch/rules.yml` | Your rules (mode 0600, editable by hand). |\n| `~/.sheep-feeds-cli/watch/hits.db` | SQLite log of every fired hit (mode 0600). |\n| `~/.sheep-feeds-cli/watch/state.json` | Per-feed cursor so each cycle only asks for new items. |\n\nThe watch directory is created on first use with mode 0700.\n\n### Caps and defaults\n\n- Max 50 rules per install (anti-DoS for the local agent).\n- Per-cycle fetch: 100 items per feed.\n- Interval: 60 s minimum, 6 h maximum (default 900 s = 15 min).\n- Webhook timeout: 10 s, no retry — the next cycle re-tries naturally\n  for items not yet acknowledged as hits.\n\n---\n\n## Maintenance\n\n```bash\nsheep-feeds --about        # Product info, links, features\nsheep-feeds --version      # Print the installed version\nsheep-feeds --init         # Create an empty config.ini with mode 0600\nsheep-feeds --setup        # Re-run the interactive setup wizard\nsheep-feeds --update       # git pull + pip upgrade\nsheep-feeds --logout       # Clear the per-session decrypted-token cache\n```\n\nTo completely wipe Watch state without touching your token:\n\n```bash\nrm -rf ~/.sheep-feeds-cli/watch/\n```\n\n`--logout` removes only the per-shell cache under `/tmp/`. The encrypted\nconfig file under `~/.sheep-feeds-cli/` is untouched; the next call asks\nfor the master password again.\n\n---\n\n## Available feeds\n\n| `feed_id` | Content | Category |\n|---|---|---|\n| `cve` | Critical vulnerabilities (NVD) | vulnerabilities |\n| `ransomware` | Ransomware victims from leak sites | ransomware |\n| `threat_intel` | APT reports, malware analysis | threat_intelligence |\n| `apt_infrastructure` | C2 / malware infra | infrastructure |\n| `data_leak` | Data breaches and dumps | data_breach |\n| `ics_scada` | ICS/SCADA advisories | ics |\n| `kaspersky` | Kaspersky SecureList posts | threat_intelligence |\n| `ioc_stream` | Real-time stream of malicious IPs/URLs/hashes | iocs |\n| `rss_news` | Aggregated security news from vendor RSS sources | news |\n\nThe server is authoritative — the CLI keeps a local allowlist as a\ntypo guard but will still call the API if you pass a feed it doesn't\nrecognise. Run `sheep-feeds list` for the canonical, server-side list.\n\n---\n\n## Output\n\n### Human (default)\n\nRich-rendered tables and panels. Auto-truncates long fields to keep the\nterminal readable. Caps at 30 items by default; use `--limit` and\n`--json` for more.\n\n### JSON (`--json`)\n\nRaw API response, pretty-printed, ready to pipe into `jq`, redirect\nto a file, or feed into a downstream tool. This is the integration\nmode — use it from cron, your SOAR / SIEM, or any pipeline tool.\n\n---\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success |\n| 1 | API error (rate limit, network, server, validation) |\n| 2 | CLI usage error (missing token, bad argument) |\n| 130 | Interrupted (Ctrl-C) |\n\nThese are stable — automation can branch on them.\n\n---\n\n## Security model\n\n- Token never appears in command-line arguments unless you use `--token`\n  (and even then it's stripped from any error output).\n- Server fields are scrubbed of ASCII control chars and Rich-markup\n  metacharacters before rendering — a hostile API response cannot\n  forge clickable links or rewrite your terminal.\n- Config file is mode 0600; the wizard refuses to load a config with\n  loose permissions (warns to `chmod 600`).\n- Encrypted token uses PBKDF2-HMAC-SHA256 with 600k iterations\n  (OWASP 2023 recommendation) and a random per-install salt.\n- Per-session decrypted-token cache (`/tmp/sheep-feeds-cli-sess-\u003cuid\u003e-\u003csid\u003e`)\n  uses `O_NOFOLLOW` to defeat symlink-pointing pre-plant attacks.\n\n---\n\n## Privacy \u0026 legal\n\n- **Privacy Policy:** https://sheep.byfranke.com/pages/privacy.html\n- **Terms of Service:** https://sheep.byfranke.com/pages/terms.html\n- **Support:** support@byfranke.com\n- **License:** byFranke License (see `LICENSE`).\n\n---\n\n## Roadmap\n\n- Streaming mode for long-lived integrations (Server-Sent Events).\n- Output adapters for OpenIOC / STIX 2.1 / MISP.\n- Per-feed schema-aware output (CVSS-coloured table for `cve`, country\n  flag emoji for `ransomware`, etc).\n\nIssues and feature requests: https://github.com/byfranke/sheep-feeds-cli/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyfranke%2Fsheep-feeds-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyfranke%2Fsheep-feeds-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyfranke%2Fsheep-feeds-cli/lists"}