feat: implement minimal viable plugin and GET /devices/ API #2
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughThis update introduces a comprehensive suite of changes for integrating a new Kolide plugin with Steampipe, facilitating SQL-based querying of devices, people, checks, and issues within a Kolide fleet. It encompasses setting up continuous integration, excluding unnecessary files, configuring the build process, and documenting the plugin's usage. The core development includes client functionality for the Kolide API, a connection configuration, error handling, and defining a new table for device data, all aimed at enhancing fleet visibility and management. Changes
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Status
Actionable comments generated: 1
Configuration used: CodeRabbit UI
Files ignored due to path filters (3)
go.modis excluded by:!**/*.modgo.sumis excluded by:!**/*.sumrenovate.jsonis excluded by:!**/*.json
Files selected for processing (16)
- .github/workflows/ci.yml (1 hunks)
- .gitignore (1 hunks)
- .goreleaser.yml (1 hunks)
- Makefile (1 hunks)
- README.md (1 hunks)
- config/kolide.spc (1 hunks)
- docs/index.md (1 hunks)
- docs/tables/kolide_k2_device.md (1 hunks)
- kolide/client/client.go (1 hunks)
- kolide/client/devices.go (1 hunks)
- kolide/connection_config.go (1 hunks)
- kolide/errors.go (1 hunks)
- kolide/plugin.go (1 hunks)
- kolide/table_kolide_k2_device.go (1 hunks)
- kolide/utils.go (1 hunks)
- main.go (1 hunks)
Files skipped from review due to trivial changes (1)
- .gitignore
Additional comments: 15
docs/tables/kolide_k2_device.md (2)
- 1-1: The spelling of "kolide_k2_device" is correct in the context of a table name, but ensure it matches exactly with the implementation in the code to avoid confusion.
- 3-3: The description is clear and concise. However, ensure that "Kolide fleet" accurately reflects the terminology used within the Kolide documentation and API.
main.go (1)
- 1-10: The
main.gofile is correctly structured for serving a Steampipe plugin. Ensure that thekolide.Pluginfunction is properly implemented in thekolidepackage.config/kolide.spc (1)
- 1-8: The configuration file is well-documented, providing clear instructions for obtaining and setting the Kolide K2 API token. Consider adding a note about the importance of keeping the API token secure.
Makefile (1)
- 1-15: The Makefile is correctly set up for building the plugin and managing configuration. Ensure that the
STEAMPIPE_INSTALL_DIRandBUILD_TAGSare correctly used in all relevant environments.kolide/errors.go (1)
- 1-20: The
shouldIgnoreErrorsfunction is well-implemented for filtering out specific error messages. Ensure that the list ofnotFoundErrorsaccurately reflects the errors that should be ignored in the context of the Kolide K2 API..github/workflows/ci.yml (1)
- 1-30: The CI workflow is correctly configured for the intended purposes. Ensure that the Go version specified (
1.21.*) is compatible with the project's requirements and that the lint timeout (10m) is sufficient for the project's size.kolide/connection_config.go (1)
- 1-28: The connection configuration schema and access functions are correctly implemented. Ensure that the
api_tokenattribute is properly handled and secured throughout the plugin's lifecycle.README.md (1)
- 1-27: The README is well-structured and informative. Ensure that all links are correct and that the instructions for installation and configuration are clear and accurate.
kolide/plugin.go (1)
- 10-26: The plugin configuration and setup in
Pluginfunction looks well-structured and follows the Steampipe SDK guidelines. The use ofDefaultTransformandDefaultIgnoreConfigis appropriate for handling common data transformations and error scenarios. The table map is correctly defined, linking to thetableKolideK2Devicefunction for device data.kolide/client/client.go (1)
- 7-41: The implementation of the
Clientstruct and its methods inkolide/client/client.gois clear and follows good practices for API client design in Go. The use of functional options for client configuration (WithAuth) is a flexible approach that allows for future extensions. However, consider adding documentation comments to public types and functions to improve code readability and maintainability..goreleaser.yml (1)
- 1-44: The
.goreleaser.ymlconfiguration is well-structured and covers the necessary build environments for Linux and Darwin platforms, including both amd64 and arm64 architectures. The use ofgo mod tidyas a pre-hook ensures that dependencies are clean and up-to-date. The archive and checksum configurations are set up correctly to package the builds and generate checksums for verification. The changelog configuration to exclude certain commits (e.g., docs and tests) from the changelog is a good practice to keep the changelog focused on significant changes.kolide/utils.go (1)
- 12-37: The
connectfunction inkolide/utils.goeffectively handles the creation and caching of the Kolide API client. It properly checks for the API token in both the plugin configuration and environment variables, providing flexibility in how the token can be supplied. However, consider adding error logging directly within theconnectfunction for cases where the API token is missing or invalid, to aid in debugging connection issues.kolide/client/devices.go (1)
- 8-46: The
DeviceListResponseandDevicestructs inkolide/client/devices.goare well-defined and match the expected JSON structure from the Kolide API. TheGetDevicesmethod correctly handles API requests, including error checking and JSON unmarshalling. To further improve error handling, consider including the HTTP status code in error messages when the response is not in a success state, to provide more context on why the request failed.kolide/table_kolide_k2_device.go (1)
- 11-72: The table definition in
kolide/table_kolide_k2_device.gois comprehensive, covering a wide range of device attributes. The use oftransform.FromField("Name")for thetitlecolumn is a good practice for ensuring consistency with Steampipe conventions. In thelistDevicesfunction, the error logging and handling are appropriately implemented. However, consider adding pagination support to theGetDevicesmethod andlistDevicesfunction to handle scenarios where the number of devices exceeds the API's single-page limit.
docs/index.md
Outdated
Comment on lines
1
to
91
| --- | ||
| organization: Grendel Consulting | ||
| category: ["asset management"] | ||
| brand_color: "#7450F6" | ||
| display_name: Kolide K2 | ||
| name: kolide | ||
| description: Kolide gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints | ||
| og_description: Query Kolide with SQL! Open source CLI. No DB required. | ||
| og_image: "/images/plugins/grendel-consulting/kolide-social-graphic.png" | ||
| icon_url: "/images/plugins/grendel-consulting/kolide.svg" | ||
| --- | ||
|
|
||
| # Kolide + Steampipe | ||
|
|
||
| [Kolide]() gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints. | ||
|
|
||
| [Steampipe](https://steampipe.io) is an open-source zero-ETL engine to instantly query cloud APIs using SQL. | ||
|
|
||
| This is an unofficial plugin, leveraging the public [Kolide K2 API](https://www.kolide.com/docs/developers/api) through the Steampipe engine. Prospective users are encouraged to undergo their usual due diligence in using third-party software. | ||
|
|
||
| List all devices in your Kolide fleet | ||
|
|
||
| ```sql | ||
| select | ||
| id, | ||
| serial, | ||
| name | ||
| from | ||
| kolide_k2_device | ||
| ``` | ||
| ``` | ||
| +------+------------+---------+ | ||
| | id | serial | name | | ||
| +------+------------+---------+ | ||
| | 1553 | X02YZ1ZYZX | ikebana | | ||
| +------+------------+---------+ | ||
| ``` | ||
|
|
||
| ## Documentation | ||
|
|
||
| - [Table Definitions and Examples]() | ||
|
|
||
| ## Get Started | ||
|
|
||
| ### Installation | ||
|
|
||
| Download and install the latest Kolide plugin: | ||
|
|
||
| ```zsh | ||
| steampipe plugin install grendel-consulting/kolide | ||
| ``` | ||
|
|
||
| ### Credentials | ||
|
|
||
| | Item | Description | | ||
| |-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | Credentials | Kolide requires an [API token](https://www.kolide.com/docs/developers/api#authentication), which can be created by an administrator with "Full Access" permissions. | | ||
| | Permissions | By default, your Kolide API token will only have access to read-only endpoints; this should be sufficient for using this plugin. | | ||
| | Radius | Each connection represents a single Kolide account. You will need to manage token rotation and revocation, as Kolide API tokens have no in-built expiry. | | ||
| | Resolution | 1. Credentials explicitly set in a steampipe config file (`~/.steampipe/config/kolide.spc`)<br />2. Credentials specified in environment variables, e.g., `KOLIDE_API_TOKEN`. | | ||
|
|
||
| ### Configuraion | ||
|
|
||
| Installing the latest Kolide plugin will create a config file (`~/.steampipe/config/kolide.spc`) with a single connection named `kolide`: | ||
|
|
||
| Configure your account details in `~/.steampipe/config/kolide.spc`: | ||
|
|
||
| ```hcl | ||
| connection "kolide" { | ||
| plugin = "grendel-consulting/kolide" | ||
|
|
||
| # Your Kolide K2 API key. Required. | ||
| # Get your API key from Kolide, instructions here: https://www.kolide.com/docs/developers/api#creating-an-api-key. | ||
| # Alternately you set with the `KOLIDE_API_TOKEN` environment variable. | ||
| # api_key = "k2sk_v1_thisIsOurExampleKey" | ||
| } | ||
| ``` | ||
|
|
||
| Alternatively, and **only if the `api_token` is omitted** in the connections, you can use the Kolide environment variable to obtain credentials only if api_token is not specified in the connection: | ||
|
|
||
| ```zsh | ||
| export KOLIDE_K2_TOKEN=k2sk_v1_thisIsOurExampleKey | ||
| ``` | ||
|
|
||
| ## Multiple Connections | ||
|
|
||
| You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) | ||
|
|
||
| ## Get Involved | ||
|
|
||
| * Open source: https://github.com/grendel-consulting/steampipe-plugin-kolide |
There was a problem hiding this comment.
The documentation in docs/index.md is clear and provides a good overview of the plugin's capabilities, installation steps, and usage examples. The inclusion of environment variable configuration and multiple connection setups is helpful for users. However, there are a few typographical errors and inconsistencies that should be corrected for clarity and professionalism. For example, "valueable" should be corrected to "valuable", and "Configuraion" should be corrected to "Configuration". Additionally, ensure that all links (e.g., [Kolide]() and [Table Definitions and Examples]()) are correctly populated with the appropriate URLs.
- valueable
+ valuable
- Configuraion
+ ConfigurationCommittable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
Suggested change
| --- | |
| organization: Grendel Consulting | |
| category: ["asset management"] | |
| brand_color: "#7450F6" | |
| display_name: Kolide K2 | |
| name: kolide | |
| description: Kolide gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints | |
| og_description: Query Kolide with SQL! Open source CLI. No DB required. | |
| og_image: "/images/plugins/grendel-consulting/kolide-social-graphic.png" | |
| icon_url: "/images/plugins/grendel-consulting/kolide.svg" | |
| --- | |
| # Kolide + Steampipe | |
| [Kolide]() gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints. | |
| [Steampipe](https://steampipe.io) is an open-source zero-ETL engine to instantly query cloud APIs using SQL. | |
| This is an unofficial plugin, leveraging the public [Kolide K2 API](https://www.kolide.com/docs/developers/api) through the Steampipe engine. Prospective users are encouraged to undergo their usual due diligence in using third-party software. | |
| List all devices in your Kolide fleet | |
| ```sql | |
| select | |
| id, | |
| serial, | |
| name | |
| from | |
| kolide_k2_device | |
| ``` | |
| ``` | |
| +------+------------+---------+ | |
| | id | serial | name | | |
| +------+------------+---------+ | |
| | 1553 | X02YZ1ZYZX | ikebana | | |
| +------+------------+---------+ | |
| ``` | |
| ## Documentation | |
| - [Table Definitions and Examples]() | |
| ## Get Started | |
| ### Installation | |
| Download and install the latest Kolide plugin: | |
| ```zsh | |
| steampipe plugin install grendel-consulting/kolide | |
| ``` | |
| ### Credentials | |
| | Item | Description | | |
| |-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | |
| | Credentials | Kolide requires an [API token](https://www.kolide.com/docs/developers/api#authentication), which can be created by an administrator with "Full Access" permissions. | | |
| | Permissions | By default, your Kolide API token will only have access to read-only endpoints; this should be sufficient for using this plugin. | | |
| | Radius | Each connection represents a single Kolide account. You will need to manage token rotation and revocation, as Kolide API tokens have no in-built expiry. | | |
| | Resolution | 1. Credentials explicitly set in a steampipe config file (`~/.steampipe/config/kolide.spc`)<br />2. Credentials specified in environment variables, e.g., `KOLIDE_API_TOKEN`. | | |
| ### Configuraion | |
| Installing the latest Kolide plugin will create a config file (`~/.steampipe/config/kolide.spc`) with a single connection named `kolide`: | |
| Configure your account details in `~/.steampipe/config/kolide.spc`: | |
| ```hcl | |
| connection "kolide" { | |
| plugin = "grendel-consulting/kolide" | |
| # Your Kolide K2 API key. Required. | |
| # Get your API key from Kolide, instructions here: https://www.kolide.com/docs/developers/api#creating-an-api-key. | |
| # Alternately you set with the `KOLIDE_API_TOKEN` environment variable. | |
| # api_key = "k2sk_v1_thisIsOurExampleKey" | |
| } | |
| ``` | |
| Alternatively, and **only if the `api_token` is omitted** in the connections, you can use the Kolide environment variable to obtain credentials only if api_token is not specified in the connection: | |
| ```zsh | |
| export KOLIDE_K2_TOKEN=k2sk_v1_thisIsOurExampleKey | |
| ``` | |
| ## Multiple Connections | |
| You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) | |
| ## Get Involved | |
| * Open source: https://github.com/grendel-consulting/steampipe-plugin-kolide | |
| --- | |
| organization: Grendel Consulting | |
| category: ["asset management"] | |
| brand_color: "#7450F6" | |
| display_name: Kolide K2 | |
| name: kolide | |
| description: Kolide gives you accurate, valuable and complete fleet visibility across Mac, Windows and Linux endpoints | |
| og_description: Query Kolide with SQL! Open source CLI. No DB required. | |
| og_image: "/images/plugins/grendel-consulting/kolide-social-graphic.png" | |
| icon_url: "/images/plugins/grendel-consulting/kolide.svg" | |
| --- | |
| # Kolide + Steampipe | |
| [Kolide]() gives you accurate, valuable and complete fleet visibility across Mac, Windows and Linux endpoints. | |
| [Steampipe](https://steampipe.io) is an open-source zero-ETL engine to instantly query cloud APIs using SQL. | |
| This is an unofficial plugin, leveraging the public [Kolide K2 API](https://www.kolide.com/docs/developers/api) through the Steampipe engine. Prospective users are encouraged to undergo their usual due diligence in using third-party software. | |
| List all devices in your Kolide fleet | |
| ```sql | |
| select | |
| id, | |
| serial, | |
| name | |
| from | |
| kolide_k2_device |
+------+------------+---------+
| id | serial | name |
+------+------------+---------+
| 1553 | X02YZ1ZYZX | ikebana |
+------+------------+---------+
Documentation
Get Started
Installation
Download and install the latest Kolide plugin:
steampipe plugin install grendel-consulting/kolideCredentials
| Item | Description |
|---|---|
| Credentials | Kolide requires an API token, which can be created by an administrator with "Full Access" permissions. |
| Permissions | By default, your Kolide API token will only have access to read-only endpoints; this should be sufficient for using this plugin. |
| Radius | Each connection represents a single Kolide account. You will need to manage token rotation and revocation, as Kolide API tokens have no in-built expiry. |
| Resolution | 1. Credentials explicitly set in a steampipe config file (~/.steampipe/config/kolide.spc)2. Credentials specified in environment variables, e.g., KOLIDE_API_TOKEN. |
Configuration
Installing the latest Kolide plugin will create a config file (~/.steampipe/config/kolide.spc) with a single connection named kolide:
Configure your account details in ~/.steampipe/config/kolide.spc:
connection "kolide" {
plugin = "grendel-consulting/kolide"
# Your Kolide K2 API key. Required.
# Get your API key from Kolide, instructions here: https://www.kolide.com/docs/developers/api#creating-an-api-key.
# Alternately you set with the `KOLIDE_API_TOKEN` environment variable.
# api_key = "k2sk_v1_thisIsOurExampleKey"
}Alternatively, and only if the api_token is omitted in the connections, you can use the Kolide environment variable to obtain credentials only if api_token is not specified in the connection:
export KOLIDE_K2_TOKEN=k2sk_v1_thisIsOurExampleKeyMultiple Connections
You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under Multi-Account Connections
Get Involved
</details>
<!-- suggestion_end -->
<!-- This is an auto-generated comment by CodeRabbit -->
There was a problem hiding this comment.
Review Status
Actionable comments generated: 4
Configuration used: CodeRabbit UI
Files selected for processing (2)
- docs/index.md (1 hunks)
- docs/tables/kolide_k2_device.md (1 hunks)
Additional comments: 3
docs/tables/kolide_k2_device.md (3)
- 1-1: The table name
kolide_k2_deviceis correctly spelled, but ensure consistency with the actual implementation in the plugin code.Verification successful
The table name
kolide_k2_deviceis correctly spelled and consistent with the actual implementation in the plugin code, as confirmed by the search results in the Go codebase. This verifies the accuracy of the documentation regarding the table name.* 3-3: Ensure the description accurately reflects the data provided by the `kolide_k2_device` table and matches the capabilities of the Kolide K2 API. * 9-15: The SQL example provided is clear and demonstrates how to retrieve basic device information. Ensure the fields `name` and `serial` are available and correctly documented in the Kolide K2 API.Scripts Executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify the table name matches the implementation ast-grep --lang go --pattern $'Table("kolide_k2_device")'Length of output: 58
Script:
#!/bin/bash # Broaden the search for the table name using ripgrep rg "kolide_k2_device" -t goLength of output: 375
|
|
||
| # Kolide + Steampipe | ||
|
|
||
| [Kolide]() gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints. |
There was a problem hiding this comment.
Correct the spelling of "valuable" to maintain professionalism in the documentation.
- valueable
+ valuableCommittable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
Suggested change
| [Kolide]() gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints. | |
| [Kolide]() gives you accurate, valuable and complete fleet visibility across Mac, Windows and Linux endpoints. |
Ensure all links, such as [Kolide]() and [Table Definitions and Examples](), are correctly populated with the appropriate URLs to provide users with easy access to additional information.
- [Kolide]()
+ [Kolide](https://www.kolide.com)
- [Table Definitions and Examples](/plugins/grendel-consulting/kolide/tables)
+ [Table Definitions and Examples](https://steampipe.io/plugins/grendel-consulting/kolide/tables)Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
Suggested change
| [Kolide]() gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints. | |
| [Kolide](https://www.kolide.com) gives you accurate, valueable and complete fleet visibility across Mac, Windows and Linux endpoints. |
|
|
||
| ## Multiple Connections | ||
|
|
||
| You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) |
There was a problem hiding this comment.
Correct the spelling of "connections" to maintain professionalism in the documentation.
- connecions
+ connectionsCommittable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
Suggested change
| You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) | |
| You may create multiple Kolide connections to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) |
Consider using "organizations" consistently in the documentation to align with American English spelling, unless specifically targeting a British English audience.
- client organisations
+ client organizationsCommittable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
Suggested change
| You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organisations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) | |
| You may create multiple Kolide connecions to aggregate queries across multiple Kolide fleets if, for example, you're managing devices on multiple client organizations. You can read up in more detail under [Multi-Account Connections](https://steampipe.io/docs/managing/connections#using-aggregators) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
New Features
.gitignorefile to exclude unnecessary files from version control.Makefilefor installing and reconfiguring a plugin for Steampipe.Documentation
Chores