|
1 | | -# tailpipe-plugin-github |
| 1 | +# GitHub Plugin for Tailpipe |
| 2 | + |
| 3 | +[Tailpipe](https://tailpipe.io) is an open-source CLI tool that allows you to collect logs and query them with SQL. |
| 4 | + |
| 5 | +[GitHub](https://www.github.com/) is a provider of Internet hosting for software development and version control using Git. It offers the distributed version control and source code management (SCM) functionality of Git, plus its own features. |
| 6 | + |
| 7 | +The [GitHub Plugin for Tailpipe](https://hub.tailpipe.io/plugins/turbot/github) allows you to collect and query GitHub logs using SQL to track activity, monitor trends, detect anomalies, and more! |
| 8 | + |
| 9 | +- **[Get started →](https://hub.tailpipe.io/plugins/turbot/github)** |
| 10 | +- Documentation: [Table definitions & examples](https://hub.tailpipe.io/plugins/turbot/github/tables) |
| 11 | +- Community: [Join #tailpipe on Slack →](https://turbot.com/community/join) |
| 12 | +- Get involved: [Issues](https://github.com/turbot/tailpipe-plugin-github/issues) |
| 13 | + |
| 14 | +Collect and query logs: |
| 15 | + |
| 16 | + |
| 17 | +## Getting Started |
| 18 | + |
| 19 | +Install Tailpipe from the [downloads](https://tailpipe.io/downloads) page: |
| 20 | + |
| 21 | +```sh |
| 22 | +# MacOS |
| 23 | +brew install turbot/tap/tailpipe |
| 24 | +``` |
| 25 | + |
| 26 | +```sh |
| 27 | +# Linux or Windows (WSL) |
| 28 | +sudo /bin/sh -c "$(curl -fsSL https://tailpipe.io/install/tailpipe.sh)" |
| 29 | +``` |
| 30 | + |
| 31 | +Install the plugin: |
| 32 | + |
| 33 | +```sh |
| 34 | +tailpipe plugin install github |
| 35 | +``` |
| 36 | + |
| 37 | +Configure your [connection credentials](https://hub.tailpipe.io/plugins/turbot/github#connection-credentials), table partition, and data source ([examples](https://hub.tailpipe.io/plugins/turbot/github/tables/github_audit_log#example-configurations)): |
| 38 | + |
| 39 | +```sh |
| 40 | +vi ~/.tailpipe/config/github.tpc |
| 41 | +``` |
| 42 | + |
| 43 | +```hcl |
| 44 | +partition "github_audit_log" "my_logs" { |
| 45 | + source "file" { |
| 46 | + paths = ["/Users/myuser/github_logs"] |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +Download, enrich, and save logs from your source ([examples](https://tailpipe.io/docs/reference/cli/collect)): |
| 52 | + |
| 53 | +```sh |
| 54 | +tailpipe collect github_audit_log |
| 55 | +``` |
| 56 | + |
| 57 | +Enter interactive query mode: |
| 58 | + |
| 59 | +```sh |
| 60 | +tailpipe query |
| 61 | +``` |
| 62 | + |
| 63 | +Run a query: |
| 64 | + |
| 65 | +```sql |
| 66 | +select |
| 67 | + action, |
| 68 | + count(*) as event_count |
| 69 | +from |
| 70 | + github_audit_log |
| 71 | +group by |
| 72 | + action |
| 73 | +order by |
| 74 | + event_count desc; |
| 75 | +``` |
| 76 | + |
| 77 | +```sh |
| 78 | ++---------------------------------------+-------------+ |
| 79 | +| action | event_count | |
| 80 | ++---------------------------------------+-------------+ |
| 81 | +| pull_request.create | 7913 | |
| 82 | +| pull_request.merge | 5754 | |
| 83 | +| issue_comment.update | 4292 | |
| 84 | +| protected_branch.policy_override | 3304 | |
| 85 | +| packages.package_version_published | 2983 | |
| 86 | +| pull_request_review.submit | 2674 | |
| 87 | +| pull_request.close | 2200 | |
| 88 | +| pull_request_review_comment.create | 1875 | |
| 89 | +| pull_request.create_review_request | 1793 | |
| 90 | +| repository_vulnerability_alert.create | 1644 | |
| 91 | ++---------------------------------------+-------------+ |
| 92 | +``` |
| 93 | + |
| 94 | +## Detections as Code with Powerpipe |
| 95 | + |
| 96 | +Pre-built dashboards and detections for the GitHub plugin are available in [Powerpipe](https://powerpipe.io) mods, helping you monitor and analyze activity across your GitHub accounts. |
| 97 | + |
| 98 | +For example, the [GitHub Audit Logs Detections mod](https://hub.powerpipe.io/mods/turbot/tailpipe-mod-github-cloudtrail-log-detections) scans your CloudTrail logs for anomalies, such as an S3 bucket being made public or a change in your VPC network infrastructure. |
| 99 | + |
| 100 | +Dashboards and detections are [open source](https://github.com/topics/tailpipe-mod), allowing easy customization and collaboration. |
| 101 | + |
| 102 | +To get started, choose a mod from the [Powerpipe Hub](https://hub.powerpipe.io/?engines=tailpipe&q=github). |
| 103 | + |
| 104 | + |
| 105 | + |
| 106 | +## Developing |
| 107 | + |
| 108 | +Prerequisites: |
| 109 | + |
| 110 | +- [Tailpipe](https://tailpipe.io/downloads) |
| 111 | +- [Golang](https://golang.org/doc/install) |
| 112 | + |
| 113 | +Clone: |
| 114 | + |
| 115 | +```sh |
| 116 | +git clone https://github.com/turbot/tailpipe-plugin-github.git |
| 117 | +cd tailpipe-plugin-github |
| 118 | +``` |
| 119 | + |
| 120 | +After making your local changes, build the plugin, which automatically installs the new version to your `~/.tailpipe/plugins` directory: |
| 121 | + |
| 122 | +```sh |
| 123 | +make |
| 124 | +``` |
| 125 | + |
| 126 | +Re-collect your data: |
| 127 | + |
| 128 | +```sh |
| 129 | +tailpipe collect github_audit_log |
| 130 | +``` |
| 131 | + |
| 132 | +Try it! |
| 133 | + |
| 134 | +```sh |
| 135 | +tailpipe query |
| 136 | +> .inspect github_audit_log |
| 137 | +``` |
| 138 | + |
| 139 | +## Open Source & Contributing |
| 140 | + |
| 141 | +This repository is published under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) (source code) and [CC BY-NC-ND](https://creativecommons.org/licenses/by-nc-nd/2.0/) (docs) licenses. Please see our [code of conduct](https://github.com/turbot/.github/blob/main/CODE_OF_CONDUCT.md). We look forward to collaborating with you! |
| 142 | + |
| 143 | +[Tailpipe](https://tailpipe.io) is a product produced from this open source software, exclusively by [Turbot HQ, Inc](https://turbot.com). It is distributed under our commercial terms. Others are allowed to make their own distribution of the software, but cannot use any of the Turbot trademarks, cloud services, etc. You can learn more in our [Open Source FAQ](https://turbot.com/open-source). |
| 144 | + |
| 145 | +## Get Involved |
| 146 | + |
| 147 | +**[Join #tailpipe on Slack →](https://turbot.com/community/join)** |
| 148 | + |
| 149 | +Want to help but don't know where to start? Pick up one of the `help wanted` issues: |
| 150 | + |
| 151 | +- [Tailpipe](https://github.com/turbot/tailpipe/labels/help%20wanted) |
| 152 | +- [GitHub Plugin](https://github.com/turbot/tailpipe-plugin-github/labels/help%20wanted) |
0 commit comments