Skip to content

Commit

Permalink
[github plugin] split the field github.repo into github.repo.name and…
Browse files Browse the repository at this point in the history
… github.repo.url for easier to write rules + fix bad indentation in the registry table

Signed-off-by: Thomas Labarussias <[email protected]>
  • Loading branch information
Issif committed Sep 17, 2024
1 parent 6d1d580 commit a0e00e9
Show file tree
Hide file tree
Showing 7 changed files with 76 additions and 84 deletions.
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,8 +83,7 @@ These comments and the text between them should not be edited by hand -->
| [k8smeta](https://github.com/falcosecurity/plugins/tree/main/plugins/k8smeta) | **Field Extraction** <br/> `syscall` | Enriche Falco syscall flow with Kubernetes Metadata <br/><br/> Authors: [The Falco Authors](https://falco.org/community) <br/> License: Apache-2.0 |
| [k8saudit-gke](https://github.com/falcosecurity/plugins/tree/main/plugins/k8saudit-gke) | **Event Sourcing** <br/>ID: 16 <br/>`k8s_audit` <br/>**Field Extraction** <br/> `k8s_audit` | Read Kubernetes Audit Events from GKE Clusters <br/><br/> Authors: [The Falco Authors](https://falco.org/community) <br/> License: Apache-2.0 |
| [journald](https://github.com/gnosek/falco-journald-plugin) | **Event Sourcing** <br/>ID: 17 <br/>`journal` <br/>**Field Extraction** <br/> `journal` | Read Journald events into Falco <br/><br/> Authors: [Grzegorz Nosek](https://github.com/gnosek/falco-journald-plugin) <br/> License: Apache-2.0 |
| [kafka](https://github.com/falcosecurity/plugins/tree/main/plugins/kafka) | **Event Sourcing** <br/>ID: 18 <br/>`kafka` | Read events from Kafka topics into Falco
<br/><br/> Authors: [Hunter Madison](https://falco.org/community) <br/> License: Apache-2.0 |
| [kafka](https://github.com/falcosecurity/plugins/tree/main/plugins/kafka) | **Event Sourcing** <br/>ID: 18 <br/>`kafka` | Read events from Kafka topics into Falco <br/><br/> Authors: [Hunter Madison](https://falco.org/community) <br/> License: Apache-2.0 |
| [gitlab](https://github.com/an1245/falco-plugin-gitlab) | **Event Sourcing** <br/>ID: 19 <br/>`gitlab` <br/>**Field Extraction** <br/> `gitlab` | Falco plugin providing basic runtime threat detection and auditing logging for GitLab <br/><br/> Authors: [Andy](https://github.com/an1245/falco-plugin-gitlab/issues) <br/> License: Apache-2.0 |
| [keycloak](https://github.com/mattiaforc/falco-keycloak-plugin) | **Event Sourcing** <br/>ID: 20 <br/>`keycloak` <br/>**Field Extraction** <br/> `keycloak` | Falco plugin for sourcing and extracting Keycloak user/admin events <br/><br/> Authors: [Mattia Forcellese](https://github.com/mattiaforc/falco-keycloak-plugin/issues) <br/> License: Apache-2.0 |

Expand Down
82 changes: 33 additions & 49 deletions plugins/github/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,113 +2,97 @@

## v0.7.5

* [`980fa2e`](https://github.com/falcosecurity/plugins/commit/980fa2e4) update(plugins/github): upgrade sdk and deps

- [`980fa2e`](https://github.com/falcosecurity/plugins/commit/980fa2e4) update(plugins/github): upgrade sdk and deps

## v0.7.4


## v0.7.3

* [`9298bcb`](https://github.com/falcosecurity/plugins/commit/9298bcb5) update(github): bump version to 0.7.3

* [`6f7ef79`](https://github.com/falcosecurity/plugins/commit/6f7ef799) build(deps): bump golang.org/x/net in /plugins/github
- [`9298bcb`](https://github.com/falcosecurity/plugins/commit/9298bcb5) update(github): bump version to 0.7.3

- [`6f7ef79`](https://github.com/falcosecurity/plugins/commit/6f7ef799) build(deps): bump golang.org/x/net in /plugins/github

## v0.7.2

* [`f37dd74`](https://github.com/falcosecurity/plugins/commit/f37dd748) chore(github): bump version to 0.7.2

- [`f37dd74`](https://github.com/falcosecurity/plugins/commit/f37dd748) chore(github): bump version to 0.7.2

## v0.7.1

* [`b0a2735`](https://github.com/falcosecurity/plugins/commit/b0a27351) fix(plugins/github): add length check in if statement

* [`5e2953f`](https://github.com/falcosecurity/plugins/commit/5e2953f8) build(deps): bump google.golang.org/protobuf in /plugins/github
- [`b0a2735`](https://github.com/falcosecurity/plugins/commit/b0a27351) fix(plugins/github): add length check in if statement

- [`5e2953f`](https://github.com/falcosecurity/plugins/commit/5e2953f8) build(deps): bump google.golang.org/protobuf in /plugins/github

## v0.7.0

* [`3a7f1b1`](https://github.com/falcosecurity/plugins/commit/3a7f1b19) fix(plugins/github): add a check that before and after commit IDs aren't null...

* [`81ccd91`](https://github.com/falcosecurity/plugins/commit/81ccd91d) build(deps): bump golang.org/x/net in /plugins/github
- [`3a7f1b1`](https://github.com/falcosecurity/plugins/commit/3a7f1b19) fix(plugins/github): add a check that before and after commit IDs aren't null...

- [`81ccd91`](https://github.com/falcosecurity/plugins/commit/81ccd91d) build(deps): bump golang.org/x/net in /plugins/github

## v0.6.1


## v0.6.0

* [`044d7d3`](https://github.com/falcosecurity/plugins/commit/044d7d3e) fix(plugins/github): fix small typo
- [`044d7d3`](https://github.com/falcosecurity/plugins/commit/044d7d3e) fix(plugins/github): fix small typo

* [`4c22035`](https://github.com/falcosecurity/plugins/commit/4c220355) feat(plugins/github): add github tag to all rules in ruleset file

* [`409260a`](https://github.com/falcosecurity/plugins/commit/409260ab) fix(plugins/github): fix type field extraction
- [`4c22035`](https://github.com/falcosecurity/plugins/commit/4c220355) feat(plugins/github): add github tag to all rules in ruleset file

- [`409260a`](https://github.com/falcosecurity/plugins/commit/409260ab) fix(plugins/github): fix type field extraction

## v0.5.3

* [`dc1e87e`](https://github.com/falcosecurity/plugins/commit/dc1e87e9) fix(plugins/github): fix ruleset dependencies

- [`dc1e87e`](https://github.com/falcosecurity/plugins/commit/dc1e87e9) fix(plugins/github): fix ruleset dependencies

## v0.5.2


## v0.5.1

* [`f1bd3b4`](https://github.com/falcosecurity/plugins/commit/f1bd3b4e) build(deps): bump golang.org/x/net in /plugins/github

- [`f1bd3b4`](https://github.com/falcosecurity/plugins/commit/f1bd3b4e) build(deps): bump golang.org/x/net in /plugins/github

## v0.5.0

* [`972cca0`](https://github.com/falcosecurity/plugins/commit/972cca0b) update(plugin/github): bump plugin version to v0.5.0

* [`0b6e12b`](https://github.com/falcosecurity/plugins/commit/0b6e12b5) update(rules/github): bump required_plugins_versions for github rules
- [`972cca0`](https://github.com/falcosecurity/plugins/commit/972cca0b) update(plugin/github): bump plugin version to v0.5.0

- [`0b6e12b`](https://github.com/falcosecurity/plugins/commit/0b6e12b5) update(rules/github): bump required_plugins_versions for github rules

## v0.4.0

* [`9654722`](https://github.com/falcosecurity/plugins/commit/96547228) update(plugins/github): bump plugin version to v0.4.0

* [`9f3a5e0`](https://github.com/falcosecurity/plugins/commit/9f3a5e0e) chore(plugins/github): update readme
- [`9654722`](https://github.com/falcosecurity/plugins/commit/96547228) update(plugins/github): bump plugin version to v0.4.0

* [`0b7468a`](https://github.com/falcosecurity/plugins/commit/0b7468a0) update(plugins/github): fix makefile cleanup
- [`9f3a5e0`](https://github.com/falcosecurity/plugins/commit/9f3a5e0e) chore(plugins/github): update readme

- [`0b7468a`](https://github.com/falcosecurity/plugins/commit/0b7468a0) update(plugins/github): fix makefile cleanup

## v0.3.1

* [`1bf3df4`](https://github.com/falcosecurity/plugins/commit/1bf3df4c) update(plugin/github): bump version to 0.3.1

* [`cf809fa`](https://github.com/falcosecurity/plugins/commit/cf809fa9) fix(plugins/github): correctly parse git diffs
- [`1bf3df4`](https://github.com/falcosecurity/plugins/commit/1bf3df4c) update(plugin/github): bump version to 0.3.1

- [`cf809fa`](https://github.com/falcosecurity/plugins/commit/cf809fa9) fix(plugins/github): correctly parse git diffs

## v0.3.0

* [`c2412cf`](https://github.com/falcosecurity/plugins/commit/c2412cf5) update(plugins/github): bump version to 0.3.0

- [`c2412cf`](https://github.com/falcosecurity/plugins/commit/c2412cf5) update(plugins/github): bump version to 0.3.0

## v0.2.0

* [`d9c1f08`](https://github.com/falcosecurity/plugins/commit/d9c1f084) update(plugins/github): adapt plugin for plugin-sdk-go v0.4.0

* [`71f653f`](https://github.com/falcosecurity/plugins/commit/71f653f3) chore(plugins/github): address review suggestions

* [`32cccff`](https://github.com/falcosecurity/plugins/commit/32cccff1) chore(plugins/github): use log instead of fmt prints
- [`d9c1f08`](https://github.com/falcosecurity/plugins/commit/d9c1f084) update(plugins/github): adapt plugin for plugin-sdk-go v0.4.0

* [`dbf7459`](https://github.com/falcosecurity/plugins/commit/dbf7459f) chore(plugins/github): reduce method visibility
- [`71f653f`](https://github.com/falcosecurity/plugins/commit/71f653f3) chore(plugins/github): address review suggestions

* [`a1ef331`](https://github.com/falcosecurity/plugins/commit/a1ef331c) chore(plugins/github): solve warnings
- [`32cccff`](https://github.com/falcosecurity/plugins/commit/32cccff1) chore(plugins/github): use log instead of fmt prints

* [`c79c890`](https://github.com/falcosecurity/plugins/commit/c79c8904) refactor(plugin/github): adhere to package design and init plugin main file
- [`dbf7459`](https://github.com/falcosecurity/plugins/commit/dbf7459f) chore(plugins/github): reduce method visibility

* [`79336d4`](https://github.com/falcosecurity/plugins/commit/79336d4d) chore(plugins/github): insert copyright headers
- [`a1ef331`](https://github.com/falcosecurity/plugins/commit/a1ef331c) chore(plugins/github): solve warnings

* [`57caa6c`](https://github.com/falcosecurity/plugins/commit/57caa6c4) update(plugins/github): bump dependencies version
- [`c79c890`](https://github.com/falcosecurity/plugins/commit/c79c8904) refactor(plugin/github): adhere to package design and init plugin main file

* [`678787f`](https://github.com/falcosecurity/plugins/commit/678787f8) update(plugins/github/rules): add version dependencies in ruleset
- [`79336d4`](https://github.com/falcosecurity/plugins/commit/79336d4d) chore(plugins/github): insert copyright headers

* [`982ac09`](https://github.com/falcosecurity/plugins/commit/982ac09b) refactor(plugins/github): create package directory
- [`57caa6c`](https://github.com/falcosecurity/plugins/commit/57caa6c4) update(plugins/github): bump dependencies version

* [`86b4bc3`](https://github.com/falcosecurity/plugins/commit/86b4bc33) chore(plugins/github): apply suggestions from review
- [`678787f`](https://github.com/falcosecurity/plugins/commit/678787f8) update(plugins/github/rules): add version dependencies in ruleset

- [`982ac09`](https://github.com/falcosecurity/plugins/commit/982ac09b) refactor(plugins/github): create package directory

- [`86b4bc3`](https://github.com/falcosecurity/plugins/commit/86b4bc33) chore(plugins/github): apply suggestions from review
z
33 changes: 19 additions & 14 deletions plugins/github/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ The plugin works by installing a webhook on one or more repositories. It then re

## Usage

### Prerequisites
* You will need a github token for your account, which you can get at <https://github.com/settings/tokens>. The token needs, at a minimum, full repo scope, to be able to enumerate the user's repositories and install/remove webhooks. Therefore, in the token creation page, make sure `repo` (and its childs) are checked under `Select scopes`. The token can go in one of these two places:
* in a file called `github.token` in `~/.ghplugin` (or in the directory pointed by the `SecretsDir` init parameter)
* in an environment variable called GITHUB_PLUGIN_TOKEN
* The machine where the plugin is running needs a public address and an open firewall that allows either port 80 (for HTTP) or port 443 (for https)
### Prerequisites

- You will need a github token for your account, which you can get at <https://github.com/settings/tokens>. The token needs, at a minimum, full repo scope, to be able to enumerate the user's repositories and install/remove webhooks. Therefore, in the token creation page, make sure `repo` (and its childs) are checked under `Select scopes`. The token can go in one of these two places:
- in a file called `github.token` in `~/.ghplugin` (or in the directory pointed by the `SecretsDir` init parameter)
- in an environment variable called GITHUB_PLUGIN_TOKEN
- The machine where the plugin is running needs a public address and an open firewall that allows either port 80 (for HTTP) or port 443 (for https)

If you want to use https (**highly recommended**), name your key and certificate `server.key` and `server.crt` and put them in `~/.ghplugin` (or in the directory pointed by the `SecretsDir` init parameter). The plugin will pick them up, validate them and start an https server. If the key and certificate are not valid, the plugin will cause falco to exit with an error.

Expand All @@ -35,22 +36,25 @@ Finally, specifying `*` as open argument will cause the plugin to instrument all
### Falco configuration examples

Instrument three specific repositories:

```yaml
- name: github
library_path: libgithub.so
init_config: '{"useHTTPs":true, "websocketServerURL" :"http://foo.ngrok.io"}'
open_params: 'falcosecurity/falco, falcosecurity/libs, falcosecurity/test-infra'
- name: github
library_path: libgithub.so
init_config: '{"useHTTPs":true, "websocketServerURL" :"http://foo.ngrok.io"}'
open_params: "falcosecurity/falco, falcosecurity/libs, falcosecurity/test-infra"
```
Instrument all of the user's repositores:
```yaml
- name: github
library_path: libgithub.so
init_config: '{"websocketServerURL" :"http://foo.ngrok.io"}'
open_params: '*'
- name: github
library_path: libgithub.so
init_config: '{"websocketServerURL" :"http://foo.ngrok.io"}'
open_params: "*"
```
## Webhook lifecycle
The plugin creates a webhook for each of the instrumented repository using the token specified as the first open argument. Each webhook is configured with a unique, automatically generated secret. This allows the plugin to reject messages that don't come from the righful github webhooks.
All of the webhooks are deleted when the plugin event source gets closed (i.e. when Falco reloads or stops).
Expand All @@ -63,7 +67,8 @@ All of the webhooks are deleted when the plugin event source gets closed (i.e. w
| `github.type` | `string` | None | Message type, e.g. 'star' or 'repository'. |
| `github.action` | `string` | None | The github event action. This field typically qualifies the github.type field. For example, a message of type 'star' can have action 'created' or 'deleted'. |
| `github.user` | `string` | None | Name of the user that triggered the event. |
| `github.repo` | `string` | None | Name of the git repository where the event occurred. Github Webhook payloads contain the repository property when the event occurs from activity in a repository. |
| `github.repo.url` | `string` | None | URL of the git repository where the event occurred. Github Webhook payloads contain the repository property when the event occurs from activity in a repository. |
| `github.repo.name` | `string` | None | Name of the git repository where the event occurred. Github Webhook payloads contain the repository property when the event occurs from activity in a repository. |
| `github.org` | `string` | None | Name of the organization the git repository belongs to. |
| `github.owner` | `string` | None | Name of the repository's owner. |
| `github.repo.public` | `string` | None | 'true' if the repository affected by the action is public. 'false' otherwise. |
Expand Down
9 changes: 7 additions & 2 deletions plugins/github/pkg/github/extract.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ package github
import (
"fmt"
"io/ioutil"
"strings"

"github.com/falcosecurity/plugin-sdk-go/pkg/sdk"
"github.com/valyala/fastjson"
Expand All @@ -31,7 +32,8 @@ func (p *Plugin) Fields() []sdk.FieldEntry {
{Type: "string", Name: "github.type", Display: "Message Type", Desc: "Message type, e.g. 'star' or 'repository'."},
{Type: "string", Name: "github.action", Display: "Action Type", Desc: "The github event action. This field typically qualifies the github.type field. For example, a message of type 'star' can have action 'created' or 'deleted'."},
{Type: "string", Name: "github.user", Display: "User", Desc: "Name of the user that triggered the event."},
{Type: "string", Name: "github.repo", Display: "Repository", Desc: "Name of the git repository where the event occurred. Github Webhook payloads contain the repository property when the event occurs from activity in a repository."},
{Type: "string", Name: "github.repo.url", Display: "Repository", Desc: "URL of the git repository where the event occurred. Github Webhook payloads contain the repository property when the event occurs from activity in a repository."},
{Type: "string", Name: "github.repo.name", Display: "Repository", Desc: "Name of the git repository where the event occurred. Github Webhook payloads contain the repository property when the event occurs from activity in a repository."},
{Type: "string", Name: "github.org", Display: "Organization", Desc: "Name of the organization the git repository belongs to."},
{Type: "string", Name: "github.owner", Display: "Owner", Desc: "Name of the repository's owner."},
{Type: "string", Name: "github.repo.public", Display: "Public", Desc: "'true' if the repository affected by the action is public. 'false' otherwise."},
Expand Down Expand Up @@ -114,8 +116,11 @@ func getfieldStr(jdata *fastjson.Value, field string) (bool, string) {
res = string(jdata.GetStringBytes("action"))
case "github.user":
res = string(jdata.Get("sender", "login").GetStringBytes())
case "github.repo":
case "github.repo.url":
res = string(jdata.Get("repository", "html_url").GetStringBytes())
case "github.repo.name":
res = string(jdata.Get("repository", "html_url").GetStringBytes())
res = strings.TrimPrefix(res, "https://github.com/")
case "github.org":
res = string(jdata.Get("organization", "login").GetStringBytes())
case "github.owner":
Expand Down
2 changes: 1 addition & 1 deletion plugins/github/pkg/github/github.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ const (
PluginName = "github"
PluginDescription = "Reads github webhook events, by listening on a socket or by reading events from disk"
PluginContact = "github.com/falcosecurity/plugins"
PluginVersion = "0.7.5"
PluginVersion = "0.8.0"
PluginEventSource = "github"
ExtractEventSource = "github"
)
Expand Down
Loading

0 comments on commit a0e00e9

Please sign in to comment.