Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #1023

Merged
merged 2 commits into from
Oct 12, 2021
Merged

Update README.md #1023

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bb78ae8
Update README.md
mrinehart-r7 Oct 11, 2021
03ed87b
Update README.md
mrinehart-r7 Oct 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 4 additions & 158 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,164 +2,10 @@

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

We made a large number of our plugins open-source in order to benefit our customers, partners, and the greater community.
Welcome to the open source plugins repository for Rapid7 InsightConnect.

The integrations here include some new, some old, and many that are community supported. These are automatically released to the product marketplace from this repository for convenient orchestration.
The full list of integrations is available on our [Marketplace](https://www.rapid7.com/marketplace/).
Plugin development documentation can be found at [https://docs.rapid7.com/insightconnect/getting-started](https://docs.rapid7.com/insightconnect/getting-started) and a full list of all plugins available for InsightConnect can be found at the [Rapid7 Extension Library](https://extensions.rapid7.com).

For general questions, issues with plugins, assistance with building or enhancing plugins, or any other discussions, check out our [Rapid7 Discussion Community](https://discuss.rapid7.com/). The team is active on Discuss along with other members of the community that are able to provide assistance. If you have a direct inquiry for the team maintaining InsightConnect plugins, we can also be reached at `[email protected]`.
Please note that GitHub Issues are unmonitored by Rapid7 developers and are disabled for this repository.
## Contributing

### Table of Contents

1. [Getting Started](#getting-started)
2. [Example](#example)
3. [Plugin Support](#plugin-support)
4. [Contributing](#contributing)

### Getting Started

You can run and develop plugins from the command-line and then orchestrate them via [InsightConnect](https://www.rapid7.com/products/insightconnect/) or legacy Komand.

Plugins are stand-alone REST services that run within Docker containers. You can interact with them over HTTP via the REST service endpoints or stdin/stdout of the running container's process.

See our [developer documentation](https://docs.rapid7.com/insightconnect/getting-started/) to learn how to build a plugin using our Python SDK. To learn more about a specific plugin, see the documentation in every plugin's `help.md` file.

Dependencies:

* [Python 3](https://www.python.org/download/releases/3.0/)
* [Make](https://www.gnu.org/software/make/)
* [Docker Engine](https://www.docker.com)
* [InsightConnect plugin tooling](https://docs.rapid7.com/insightconnect/getting-started/)
* [InsightConnect validators](https://pypi.org/project/insightconnect-integrations-validators/), [pyyaml](https://pyyaml.org/), [js-yaml](https://github.com/nodeca/js-yaml), [jq](https://stedolan.github.io/jq/), [flake8](https://pypi.org/project/flake8/), [mdl](https://github.com/markdownlint/markdownlint) for the helper scripts in `tools/`.
* [Pre-commit](https://pre-commit.com/) and [Black](https://github.com/psf/black)

For a quick & easy way to install tooling dependencies, run `update-tools.sh` from the `tools/` directory in this repository!

### Example

![Make Menu](./.github/make_menu_example.png)

Let's build and run a plugin from this repository.

We'll use the Dig plugin as an example. Dig is a command-line network utility for DNS.

```
$ cd dig
$ make
[*] Use ``make menu`` for available targets
[*] Including available Makefiles: ../tools/Makefiles/Colors.mk ../tools/Makefiles/Helpers.mk
--
[*] Building plugin image
docker build --pull -t rapid7/dig:1.0.1 .
Sending build context to Docker daemon 208.9kB
Step 1/14 : FROM komand/python-3-37-slim-plugin:3
2: Pulling from komand/python-3-37-slim-plugin
Digest: sha256:74c67981efc06a27c0e650bc0bc3a681c87bc193869a3316945480c26371f7f4
Status: Image is up to date for komand/python-3-37-slim-plugin:3
...
```

Now, let's create the runner script and then run the plugin:

```
$ make runner
[*] Use ``make menu`` for available targets
[*] Including available Makefiles: ../tools/Makefiles/Colors.mk ../tools/Makefiles/Helpers.mk
--
[*] Creating link to run.sh |

$ ./run.sh -R tests/search_by_domain.json -j

Running: cat tests/forward.json | docker run --rm -i rapid7/dig:1.0.1 run | grep -- ^\{ | jq -r '.body | try(.log | split("\n") | .[]),.output'
rapid7/Dig:1.0.1. Step name: forward
Executing command /usr/bin/dig google.com A

{
"status": "NOERROR",
"fulloutput": "\n; <<>> DiG 9.12.3 <<>> google.com A\n;; global options: +cmd\n;; Got answer:\n;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 52959\n;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0\n\n;; QUESTION SECTION:\n;google.com.\t\t\tIN\tA\n\n;; ANSWER SECTION:\ngoogle.com.\t\t162\tIN\tA\t172.217.12.174\n\n;; Query time: 62 msec\n;; SERVER: 192.168.65.1#53(192.168.65.1)\n;; WHEN: Thu Apr 18 17:06:37 UTC 2019\n;; MSG SIZE rcvd: 44\n\n",
"question": "google.com",
"all_answers": [
"172.217.12.174"
],
"last_answer": "172.217.12.174",
"answer": "172.217.12.174",
"nameserver": "192.168.65.1"
}
```

You can also run the plugin container in the background as a REST server:

```
$ ./run.sh -c http
Forwarding to port 10001
Running: docker run --rm -d -p 10001:10001 -i rapid7/dig:1.0.1 http
d719d45e9238d407010e656209f11b30674c2a3dd39225e232685737b111cc2d
```

Let's run the equivalent of the previous example but with a web request:

```
$ curl -d @tests/forward.json http://127.0.0.1:10001/actions/forward
{
"body": {
"log": "rapid7/Dig:1.0.1. Step name: forward\nExecuting command /usr/bin/dig google.com A\n",
"meta": {},
"output": {
"all_answers": [
"172.217.9.78"
],
"answer": "172.217.9.78",
"fulloutput": "\n; <<>> DiG 9.12.3-P4 <<>> google.com A\n;; global options: +cmd\n;; Got answer:\n;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 59113\n;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0\n\n;; QUESTION SECTION:\n;google.com.\t\t\tIN\tA\n\n;; ANSWER SECTION:\ngoogle.com.\t\t162\tIN\tA\t172.217.9.78\n\n;; Query time: 46 msec\n;; SERVER: 192.168.65.1#53(192.168.65.1)\n;; WHEN: Fri Apr 19 16:45:20 UTC 2019\n;; MSG SIZE rcvd: 44\n\n",
"last_answer": "172.217.9.78",
"nameserver": "192.168.65.1",
"question": "google.com",
"status": "NOERROR"
},
"status": "ok"
},
"type": "action_event",
"version": "v1"
}
```

You can generate sample JSON to use to test your plugin with the runner `run.sh`:

```
$ ./run.sh -c sample
Actions: [forward reverse]
Triggers: []
Sample requires sample name e.g. ``./run.sh -c sample <name>''

$ ./run.sh -c sample forward
Running: docker run --rm -i rapid7/dig:1.0.1 sample forward | jq '.'
{
"body": {
"action": "forward",
"input": {
"query": "A",
"domain": "",
"resolver": ""
},
"connection": null,
"meta": {}
},
"version": "v1",
"type": "action_start"
}
```

You can also generate all samples for a plugin with this shorthand: `./run.sh -c samples`

### Plugin Support

The `status` key in a plugin's `plugin.spec.yaml` file indicates which plugins are officially supported by Rapid7 developers (rapid7) and which ones are supported by our ecosystem of external developers or by Rapid7 as best-effort (community).

```
$ grep '^support:' microsoft_teams/plugin.spec.yaml
support: community
```

### Contributing

See our [contributing guide](./CONTRIBUTING.md).
Please see our [contribution guide](./CONTRIBUTING.md) for contributing changes back to this repository.