raygatherer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aef304a404bc427e2d066db7cf8767e73d06dc8c765b15f18b78afc68a78ee1e
+  data.tar.gz: e81748ac2ce4443e5a30ff55e63727db50148d7b1402ffebbee280c01f19a8a6
+SHA512:
+  metadata.gz: cc2ce523698c34711223d9c88a14360f98850e91650da419acb9b532e6d1e5a8f1bc8db47d418e83acf648878803a4f2811ca65403dbfcbfae071017e0ad6c3b
+  data.tar.gz: bde55ec5165b8516d9e6295a2b6215db2c54f2399b9c299497591b9d0ebe212a1d2eac19c0d10ace5324816f1a37f477ca06587125110a858488c39a587f283d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CLAUDE.md

@@ -0,0 +1,102 @@
+# PROJECT OVERVIEW
+
+Raygatherer: Ruby CLI for fetching and displaying alerts from Rayhunter (cell tower / IMSI catcher analysis device). Ruby >= 3.1.0.
+
+# QUICK REFERENCE
+
+- Run tests: `bundle exec rspec`
+- Run CLI: `bundle exec ./exe/raygatherer`
+- CI: GitHub Actions on push to master and all PRs
+- `rayhunter` itself is checked out at `/Users/mike/workspace/rayhunter/`
+
+# ARCHITECTURE
+
+- Entry point: `exe/raygatherer` → `Raygatherer::CLI.run`
+- CLI routing: `lib/raygatherer/cli.rb`
+- Commands: `lib/raygatherer/commands/` (one class per subcommand)
+- API client: `lib/raygatherer/api_client.rb` (HTTP + NDJSON parsing)
+- Formatters: `lib/raygatherer/formatters/` (human and JSON, both accept arrays)
+- Tests mirror `lib/` structure under `spec/`, plus `spec/integration/` for CLI end-to-end tests
+
+# KEY CONVENTIONS
+
+- Formatters always receive and return arrays (even when empty)
+- JSON output is always a JSON array
+- Exit codes encode alert severity for scripting use (see `show_help` in status.rb)
+- Linter: `bundle exec standardrb` (Ruby Standard Style). Write new code in standardrb style to avoid rework.
+
+# ROLE AND EXPERTISE
+
+You are a senior software engineer who follows Kent Beck's Test-Driven Development (TDD) and Tidy First principles. Your purpose is to guide development following these methodologies precisely.
+
+# CORE DEVELOPMENT PRINCIPLES
+
+- Always follow the TDD cycle: Red → Green → Refactor
+- Write the simplest failing test first
+- Implement the minimum code needed to make tests pass
+- Refactor only after tests are passing
+- Follow Beck's "Tidy First" approach by separating structural changes from behavioral changes
+- Maintain high code quality throughout development
+
+# TDD METHODOLOGY GUIDANCE
+
+- Start by writing a failing test that defines a small increment of functionality
+- Use meaningful test names that describe behavior (e.g., "should sum two positive integers")
+- Make test failures clear and informative
+- Write just enough code to make the test pass - no more
+- Once tests pass, consider if refactoring is needed
+- Repeat the cycle for new functionality
+- When fixing a defect, first write an API-level failing test then write the smallest possible test that replicates the problem then get both tests to pass.
+
+# TIDY FIRST APPROACH
+
+- Separate all changes into two distinct types:
+  1. STRUCTURAL CHANGES: Rearranging code without changing behavior (renaming, extracting methods, moving code)
+  2. BEHAVIORAL CHANGES: Adding or modifying actual functionality
+- Never mix structural and behavioral changes in the same commit
+- Always make structural changes first when both are needed
+- Validate structural changes do not alter behavior by running tests before and after
+
+# COMMIT DISCIPLINE
+
+- Only commit when:
+  1. ALL tests are passing (`bundle exec rspec`)
+  2. ALL standardrb issues are resolved (`bundle exec standardrb`); fix any issues before committing
+  3. The change represents a single logical unit of work
+  4. Commit messages clearly state whether the commit contains structural or behavioral changes
+- Use small, frequent commits rather than large, infrequent ones
+
+# CODE QUALITY STANDARDS
+
+- Eliminate duplication ruthlessly
+- Express intent clearly through naming and structure
+- Make dependencies explicit
+- Keep methods small and focused on a single responsibility
+- Minimize state and side effects
+- Use the simplest solution that could possibly work
+
+# REFACTORING GUIDELINES
+
+- Refactor only when tests are passing (in the "Green" phase)
+- Use established refactoring patterns with their proper names
+- Make one refactoring change at a time
+- Run tests after each refactoring step
+- Prioritize refactorings that remove duplication or improve clarity
+
+# EXAMPLE WORKFLOW
+
+When approaching a new feature:
+
+1. Write a simple failing test for a small part of the feature
+2. Implement the bare minimum to make it pass
+3. Run tests to confirm they pass (Green)
+4. Run `bundle exec standardrb` and fix any issues
+5. Make any necessary structural changes (Tidy First), running tests after each change
+6. Commit structural changes separately
+7. Add another test for the next small increment of functionality
+8. Repeat until the feature is complete, committing behavioral changes separately from structural ones
+
+Follow this process precisely, always prioritizing clean, well-tested code over quick implementation.
+
+Always write one test at a time, make it run, then improve structure. Always run all the tests (except long-running tests) each time.
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at 
+prelate-33.requiem@icloud.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mike Stallard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Makefile

@@ -0,0 +1,23 @@
+GEM = raygatherer-$(shell ruby -e "require_relative 'lib/raygatherer/version'; puts Raygatherer::VERSION").gem
+
+build: $(GEM)
+
+$(GEM): raygatherer.gemspec lib/**/*.rb exe/*
+	gem build raygatherer.gemspec
+
+install: $(GEM)
+	gem install $(GEM)
+
+uninstall:
+	gem uninstall raygatherer
+
+clean:
+	rm -f raygatherer-*.gem
+
+lint:
+	bundle exec standardrb
+
+test:
+	bundle exec rspec
+
+.PHONY: install uninstall clean test

data/README.md

@@ -0,0 +1,220 @@
+# Raygatherer
+
+![Build Pipeline Status](https://github.com/mjstallard/raygatherer/actions/workflows/main.yml/badge.svg)
+
+This is a CLI to interact with [Rayhunter](https://github.com/EFForg/rayhunter/). It was built with the intent of giving myself the ability to automate alerting and recording management on a Rayhunter that is not-mobile (ie., it is plugged in 24/7 in my attic). If you too wish to script or otherwise automate using your Rayhunter, you might find this to be helpful!
+
+**Important:** This is a personal side-project, and has no affiliation with or endorsement from the Rayhunter project, or the EFF. It is entirely unofficial, and without warranty.
+
+## What It Does
+
+Currently implemented:
+
+- alerts from live analysis, with severity-based exit codes
+- recording list/start/stop/delete/download
+- system stats
+- analysis queue status and triggering analysis runs
+- config show/set/test-notification
+- JSON output mode for scriptable commands
+- optional basic auth and config file support
+
+## Installation
+
+### Ruby version
+
+`raygatherer` requires Ruby `>= 3.1.0`.
+
+### Install from this repo
+
+```bash
+bundle install
+make build
+make install
+```
+
+Or install directly with RubyGems:
+
+```bash
+gem build raygatherer.gemspec
+gem install ./raygatherer-*.gem
+```
+
+## Quick Start
+
+Check CLI help:
+
+```bash
+raygatherer --help
+```
+
+Check live alerts:
+
+```bash
+raygatherer --host http://rayhunter.local alerts
+```
+
+Check live alerts as JSON:
+
+```bash
+raygatherer --host http://rayhunter.local --json alerts
+```
+
+List recordings:
+
+```bash
+raygatherer --host http://rayhunter.local recording list
+```
+
+Download a recording:
+
+```bash
+raygatherer --host http://rayhunter.local recording download 1738950000
+```
+
+Show analysis queue status:
+
+```bash
+raygatherer --host http://rayhunter.local analysis status
+```
+
+Show system stats:
+
+```bash
+raygatherer --host http://rayhunter.local stats
+```
+
+## Global Flags
+
+These can be used with any command:
+
+- `--host HOST` (required unless provided in config file)
+- `--basic-auth-user USER`
+- `--basic-auth-password PASS`
+- `--verbose`
+- `--json` (only applies to commands that support JSON output)
+
+## Configuration File
+
+By default, config is loaded from:
+
+- `~/.config/raygatherer/config.yml`
+- or `$XDG_CONFIG_HOME/raygatherer/config.yml` if `XDG_CONFIG_HOME` is set
+
+Supported keys:
+
+- `host`
+- `basic_auth_user`
+- `basic_auth_password`
+- `json`
+- `verbose`
+
+CLI flags always override config values.
+
+Example:
+
+```yaml
+host: http://rayhunter.local
+basic_auth_user: admin
+basic_auth_password: replace-me
+json: false
+verbose: false
+```
+
+## Commands
+
+Main commands:
+
+- `alerts`
+- `recording list`
+- `recording download <name> [--qmdl|--pcap|--zip] [--download-dir DIR|--save-as PATH]`
+- `recording delete <name>`
+- `recording stop`
+- `recording start`
+- `analysis status`
+- `analysis run [NAME|--all]`
+- `config show`
+- `config set` (reads JSON from stdin)
+- `config test-notification`
+- `stats`
+
+For command-specific help:
+
+```bash
+raygatherer COMMAND --help
+```
+
+Examples:
+
+```bash
+raygatherer alerts --help
+raygatherer recording download --help
+raygatherer analysis run --help
+```
+
+## Alerts Exit Codes
+
+`alerts` returns severity-based codes so shell scripts can react:
+
+- `0`: no alerts
+- `1`: error
+- `10`: low severity alert
+- `11`: medium severity alert
+- `12`: high severity alert
+
+Example:
+
+```bash
+raygatherer --host http://rayhunter.local alerts
+code=$?
+[ "$code" -ge 11 ] && echo "medium or high alert"
+```
+
+## JSON Output
+
+Commands that support `--json` return machine-readable output to `stdout`. This is intended for `jq` and/or scripts.
+
+Example:
+
+```bash
+raygatherer --host http://rayhunter.local --json config show | jq '.analyzers'
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run tests:
+
+```bash
+make test
+```
+
+Run linter:
+
+```bash
+make lint
+```
+
+Build gem:
+
+```bash
+make build
+```
+
+## Security Notes
+
+- This tool can send credentials over plaintext via HTTP if you point it at `http://...`.
+- Config files may contain credentials. Restrict permissions appropriately.
+- This is an unofficial tool. Verify behavior in your environment before relying on it.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Raygatherer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mjstallard/raygatherer/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/raygatherer

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "raygatherer"
+
+exit Raygatherer::CLI.run(ARGV)