dbotquery 0.9 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54f665596ce0a1ef9bc40d3fad0c0e208b8fcbe9b27225851584dbb5087a359c
-  data.tar.gz: 0da1bd780a74e60361ea1b7f703e9b6f15f57d31e5e6e69a4e1130a1d2a5be02
+  metadata.gz: 25ebc924a49d65ea76209ac3566a9b7fb43ca639f48cdbd6adfe0d501aaf4eb7
+  data.tar.gz: 291f70d4147726f2a8986ca269ac75c1394ed5efa887fedc1582944dd6ef81a7
 SHA512:
-  metadata.gz: 474a2bf379ae1f15e293558e756efce924a1a8b5dec015e86774fe1bc64ba6d90c8a2e84b4ad7b7a9b616257ebf0f7bd1a0f5fcf31adf37ba5f0e3e42879f307
-  data.tar.gz: 8c3e80eee61bc7437fdc5cd7b95c9ae67719b67d4381b7f08e44cca8e905df4fd0164ffd9ee0a212d58735e3228314142112999e76d01250616c018e0becb1c9
+  metadata.gz: c91abe252617ab8a6826ac99739f4c10a2ec682bece5638f21e8bd3b2d139ca937278bbbf9c994be4a49e90750a88535bf3d772cded17d3411281de57c94d380
+  data.tar.gz: f823fd53e4782df096e81b02cbe1c23a16e7496b07355e4694a54569d09ef338551c3e589d789ded1ebb2463ea4155e6a6c4572c5f1338e82a0e85bb610138e2

data/.idea/dbotquery.iml

@@ -58,6 +58,7 @@
     <orderEntry type="library" scope="PROVIDED" name="csv (v3.3.5, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.6.2, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="docile (v1.4.1, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="TEST" name="dotenv (v3.2.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="drb (v2.2.3, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="dry-configurable (v1.4.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="dry-core (v1.2.0, rbenv: 4.0.5) [gem]" level="application" />
@@ -66,6 +67,8 @@
     <orderEntry type="library" scope="PROVIDED" name="dry-logic (v1.6.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="dry-schema (v1.16.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="dry-types (v1.9.1, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday (v2.14.3, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-net_http (v3.4.4, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ffi (v1.17.4, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="fileutils (v1.8.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="gemika (v2.0.0, rbenv: 4.0.5) [gem]" level="application" />
@@ -79,6 +82,8 @@
     <orderEntry type="library" scope="PROVIDED" name="logger (v1.7.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="method_source (v1.1.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="minitest (v6.0.6, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="net-http (v0.9.1, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="octokit (v10.0.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="parallel (v2.1.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="parser (v3.3.11.1, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="prism (v1.9.0, rbenv: 4.0.5) [gem]" level="application" />
@@ -107,6 +112,7 @@
     <orderEntry type="library" scope="PROVIDED" name="rubocop-rspec (v3.10.2, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rubocop-yard (v1.3.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.13.0, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="sawyer (v0.9.3, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="securerandom (v0.4.1, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="TEST" name="simplecov (v0.22.0, rbenv: 4.0.5) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="simplecov-html (v0.13.2, rbenv: 4.0.5) [gem]" level="application" />

data/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to DBotQuery
+
+Thanks for your interest in improving DBotQuery! Bug reports, feature requests,
+and pull requests are all welcome.
+
+By participating in this project you agree to abide by our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Getting started
+
+1. Fork the repository and clone your fork.
+2. Install dependencies:
+   ```bash
+   bin/setup
+   ```
+3. Make sure the test suite passes before you change anything:
+   ```bash
+   bundle exec rake spec
+   ```
+
+Requires Ruby `>= 3.3` and Bundler.
+
+## Reporting bugs and requesting features
+
+Open an issue at <https://github.com/rickmark/dbotquery/issues>. For bug reports,
+please include:
+
+- What you expected to happen and what actually happened.
+- The exact command you ran (with any relevant flags).
+- A minimal, **sanitized** snippet of the Dependabot export that reproduces the
+  problem. Never paste real tokens, secrets, or private vulnerability data into
+  an issue.
+- Your Ruby version (`ruby -v`) and OS.
+
+## Development workflow
+
+1. Create a topic branch off `main`:
+   ```bash
+   git checkout -b my-feature
+   ```
+2. Make your change, adding or updating tests and documentation as needed.
+3. Run the full check suite locally (see below).
+4. Commit with a clear message, push to your fork, and open a pull request
+   against `main`.
+
+Keep pull requests focused — one logical change per PR makes review easier.
+
+## Quality checks
+
+All of the following should pass before you open a pull request. CI runs them
+too.
+
+```bash
+bundle exec rake spec        # RSpec test suite
+bundle exec rubocop          # style / lint
+bundle exec steep check      # RBS / Steep type checking
+```
+
+Guidelines:
+
+- **Tests.** New behavior needs test coverage; bug fixes should include a test
+  that fails before the fix and passes after. Fixtures live under `spec/fixtures`.
+- **Types.** This project uses inline RBS (`# rbs_inline: enabled`) with signatures
+  in `sig/`. When you change a public method, update the corresponding `.rbs`
+  signature so `steep check` stays green.
+- **Style.** Follow the existing code style; RuboCop is the source of truth. Match
+  the surrounding code's naming, structure, and comment density.
+- **Documentation.** Update `README.md` and command doc comments when you add or
+  change a command or option.
+
+## Architecture at a glance
+
+- `lib/d_bot_query/cli.rb` — Thor-based command-line interface (argument parsing).
+- `lib/d_bot_query/commands/` — one class per subcommand. Each command is thin and
+  delegates to the models, which keeps the CLI and the logic independently
+  testable.
+- `lib/d_bot_query/models/` — data models wrapping the Dependabot export
+  (alerts, advisories, packages, repositories, CVSS/CWE, etc.).
+- `lib/d_bot_query/octokit.rb` — optional Octokit extensions for fetching alerts
+  live from the GitHub API.
+
+When adding a new report, add a command class under `commands/`, wire it into
+`cli.rb`, and put the actual computation on the appropriate model so it can be
+unit-tested without the CLI.
+
+## Security
+
+Do not commit secrets. `GITHUB_TOKEN` and any `.env` file are git-ignored — keep
+it that way. If you discover a security issue, please avoid filing a public issue
+with sensitive details; contact the maintainer directly instead.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[MIT License](LICENSE.txt) that covers the project.

data/README.md

@@ -1,34 +1,197 @@
 # DBotQuery
 
-An example of a production ready query tool for GitHub dependabot data.
+Command-line reports for [GitHub Dependabot](https://docs.github.com/en/code-security/dependabot) exports.
+
+DBotQuery reads a JSON export of Dependabot alerts and produces machine-readable
+(JSON) reports — vulnerability summaries, SLA compliance statistics, and package
+usage searches. It is designed so that people who don't have direct access to
+GitHub (or who want the data in another system) can still see and process an
+organization's vulnerability posture.
+
+The tool does not need to talk to GitHub to produce reports: it takes an exported
+Dependabot JSON file as input, along with some options, and writes a JSON document
+to standard output. (Optional live fetching via the GitHub API is also supported —
+see [Fetching data from GitHub](#fetching-data-from-github).)
+
+## Requirements
+
+- Ruby `>= 3.3`
+- [Bundler](https://bundler.io/)
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/rickmark/dbotquery.git
+cd dbotquery
+bin/setup
+```
+
+To install the executable onto your machine as a gem:
 
 ```bash
-bundle install
-rake install
+bundle exec rake install
 ```
 
+You can then run `dbotquery` directly. Otherwise, prefix commands with
+`bundle exec` as shown below.
+
 ## Usage
 
-`bundle exec dbotquery summary`
+Every command takes a Dependabot JSON export via `-f`/`--file` and prints a JSON
+report to standard output.
+
+```bash
+bundle exec dbotquery <command> -f dependabot.json [options]
+```
+
+Run `bundle exec dbotquery help` to list commands, or
+`bundle exec dbotquery help <command>` for details on a specific one.
+
+### `summary` — count vulnerabilities
+
+Counts findings in the export, optionally filtered by state and/or severity.
+
+```bash
+# All findings
+bundle exec dbotquery summary -f dependabot.json
+
+# Only dismissed findings
+bundle exec dbotquery summary -f dependabot.json --state dismissed
+
+# Only open, critical findings
+bundle exec dbotquery summary -f dependabot.json --state open --severity critical
+```
+
+| Flag | Required | Description | Values |
+| :--- | :--- | :--- | :--- |
+| `-f`, `--file` | yes | Path to the Dependabot JSON export | `dependabot.json` |
+| `--state` | no | Only count findings in this state | `open`, `fixed`, `dismissed` |
+| `--severity` | no | Only count findings of this severity | `critical`, `high`, `medium`, `low` |
+
+Output:
+
+```json
+{ "count": 42 }
+```
+
+### `sla_stats` — SLA breaches by severity
+
+Counts vulnerabilities that have been open longer than the allowed SLA, broken
+out by severity. The SLA (in days) is:
+
+| Severity | Days |
+| :--- | :--- |
+| Low | 60 |
+| Medium | 30 |
+| High | 15 |
+| Critical | 5 |
+
+```bash
+# Using the current time to calculate age
+bundle exec dbotquery sla_stats -f dependabot.json
+
+# Using a fixed point in time (ISO 8601)
+bundle exec dbotquery sla_stats -f dependabot.json -t 2023-01-01T00:00:00Z
+```
+
+| Flag | Required | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `-f`, `--file` | yes | Path to the Dependabot JSON export | `dependabot.json` |
+| `-t`, `--time` | no | Point in time used to calculate age (ISO 8601) | `2023-01-01T00:00:00Z` |
+
+Output:
+
+```json
+{ "low": 1, "medium": 2, "high": 0, "critical": 3, "total": 6 }
+```
+
+### `repo_sla_stats` — SLA breaches by repository
+
+The same report as `sla_stats`, but broken out per repository so teams can see
+the findings specific to their code.
+
+```bash
+bundle exec dbotquery repo_sla_stats -f dependabot.json
+bundle exec dbotquery repo_sla_stats -f dependabot.json -t 2023-01-01T00:00:00Z
+```
+
+Flags are identical to `sla_stats`. Output:
+
+```json
+{
+  "org/repo":  { "low": 1, "medium": 0, "high": 2, "critical": 1, "total": 4 },
+  "org/repo2": { "low": 0, "medium": 1, "high": 0, "critical": 0, "total": 1 }
+}
+```
+
+### `package_search` — where is a package used?
+
+Answers "do we use library X?" by listing every repository where the given
+package appears.
+
+```bash
+bundle exec dbotquery package_search -f dependabot.json --package sinatra
+bundle exec dbotquery package_search -f dependabot.json --package node-forge
+```
+
+| Flag | Required | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `-f`, `--file` | yes | Path to the Dependabot JSON export | `dependabot.json` |
+| `--package` | yes | The package name to search for | `sinatra`, `puma`, `node-forge` |
+
+Output:
+
+```json
+["org/repo", "org/repo2"]
+```
+
+## Fetching data from GitHub
+
+DBotQuery ships with [Octokit](https://github.com/octokit/octokit.rb) extensions
+for pulling Dependabot alerts directly from the GitHub API, which can be used from
+the console or in your own scripts:
+
+```ruby
+client = Octokit::Client.new(access_token: ENV["GITHUB_TOKEN"])
+client.dependabot_org_alerts("my-org")
+client.dependabot_repo_alerts("my-org", "my-repo")
+```
+
+Provide the token via a `GITHUB_TOKEN` environment variable — for local
+development you can place it in a `.env` file, which is **git-ignored** and must
+never be committed. Treat these tokens as secrets and rotate them if exposed.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bundle exec rake spec   # run the test suite
+bin/console             # interactive prompt for experimentation
+```
 
-## Contributing
+The project also uses:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dbotquery. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/dbotquery/blob/main/CODE_OF_CONDUCT.md).
+- [RuboCop](https://rubocop.org/) for linting (`bundle exec rubocop`)
+- [Steep](https://github.com/soutaro/steep) / [RBS](https://github.com/ruby/rbs)
+  for type checking (`bundle exec steep check`)
+- [YARD](https://yardoc.org/) for documentation (`bundle exec rake yard`)
 
-## License
+To release a new version, update the version number in
+`lib/d_bot_query/version.rb`, then run `bundle exec rake release`, which creates a
+git tag, pushes commits and the tag, and pushes the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/rickmark/dbotquery>. Please read
+[CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. This project is
+intended to be a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
 
-## Code of Conduct
+## License
 
-Everyone interacting in the Dbotquery project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/dbotquery/blob/main/CODE_OF_CONDUCT.md).
+Available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/d_bot_query/models/alert.rb

@@ -24,6 +24,8 @@ module DBotQuery
       attribute :dismissed_by, :string
       attribute :dismissed_comment, :string
       attribute :dismissed_reason, :string
+      attribute :dismissal_request
+      attribute :assignees, :array, of: String
 
       def days_open(as_of)
         as_of = as_of&.to_date || Time.now.to_date

data/lib/d_bot_query/models/alert_collection.rb

@@ -14,6 +14,8 @@ module DBotQuery
       def initialize(alerts)
         @alerts = alerts.map do |alert|
           case alert
+          when Sawyer::Resource
+            Alert.new(alert.to_h)
           when Hash
             Alert.new(alert)
           when Alert

data/lib/d_bot_query/models/base.rb

@@ -59,7 +59,7 @@ module DBotQuery
 
         def materialize(item)
           case item
-          when Hash
+          when Hash, Array
             target_class.new(item)
           when target_class
             item

data/lib/d_bot_query/models/cvss_severity.rb

@@ -0,0 +1,12 @@
+module DBotQuery
+  module Models
+    class CVSSSeverity < Base
+      attribute :type, :symbol
+      attribute :cvss, CVSS
+
+      def initialize(item)
+        super({ type: item[0], cvss: item[1] })
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/cwe.rb

@@ -3,6 +3,9 @@
 module DBotQuery
   module Models
     class CWE < Base
+      attribute :cwe_id
+      alias_attribute :id, :cwe_id
+      attribute :name
     end
   end
 end

data/lib/d_bot_query/models/dependency.rb

@@ -7,6 +7,7 @@ module DBotQuery
       attribute :package, Package
       attribute :manifest_path
       attribute :scope
+      attribute :relationship
     end
   end
 end

data/lib/d_bot_query/models/security_advisory.rb

@@ -16,7 +16,10 @@ module DBotQuery
       attribute :references, :array, of: Reference
       attribute :vulnerabilities, :array, of: SecurityVulnerability
       attribute :cvss, CVSS
+      attribute :cvss_severities, :array, of: CVSSSeverity
       attribute :cwes, :array, of: CWE
+      attribute :epss
+      attribute :classification
     end
   end
 end

data/lib/d_bot_query/octokit.rb

@@ -0,0 +1,16 @@
+require 'octokit'
+
+module DBotQuery
+  module OctokitExtensions
+    def dependabot_org_alerts(org)
+      result = get("/orgs/#{org}/dependabot/alerts")
+      Models::AlertCollection.new(result)
+    end
+
+    def dependabot_repo_alerts(owner, repo)
+      Models::AlertCollection.new(get("/repos/#{owner}/#{repo}/dependabot/alerts"))
+    end
+  end
+end
+
+Octokit::Client.include DBotQuery::OctokitExtensions

data/lib/d_bot_query/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module DBotQuery
-  VERSION = '0.9'
+  VERSION = '1.0'
 end

data/lib/dbotquery.rb

@@ -71,8 +71,11 @@ module DBotQuery
     autoload :Reference, 'd_bot_query/models/reference'
     autoload :CVSS, 'd_bot_query/models/cvss'
     autoload :CWE, 'd_bot_query/models/cwe'
+    autoload :CVSSSeverity, 'd_bot_query/models/cvss_severity'
   end
 
+  require 'd_bot_query/octokit'
+
   def self.schema
     SCHEMA
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dbotquery
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: '1.0'
 platform: ruby
 authors:
 - Rick Mark
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: octokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -83,6 +97,7 @@ files:
 - ".reek.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - NOTES.md
 - README.md
@@ -99,6 +114,7 @@ files:
 - lib/d_bot_query/models/alert_collection.rb
 - lib/d_bot_query/models/base.rb
 - lib/d_bot_query/models/cvss.rb
+- lib/d_bot_query/models/cvss_severity.rb
 - lib/d_bot_query/models/cwe.rb
 - lib/d_bot_query/models/data_file.rb
 - lib/d_bot_query/models/dependency.rb
@@ -108,6 +124,7 @@ files:
 - lib/d_bot_query/models/security_advisory.rb
 - lib/d_bot_query/models/security_vulnerability.rb
 - lib/d_bot_query/models/vulnerability_identifier.rb
+- lib/d_bot_query/octokit.rb
 - lib/d_bot_query/version.rb
 - lib/dbotquery.rb
 - lib/schema.json