Skip to content

Commit ba357a3

Browse files
Update README.md (#1023)
* Update README.md * Update README.md Co-authored-by: PJ Mara <87435279+pmara-r7@users.noreply.github.com> Co-authored-by: PJ Mara <87435279+pmara-r7@users.noreply.github.com>
1 parent 95e938f commit ba357a3

File tree

1 file changed

+4
-158
lines changed

1 file changed

+4
-158
lines changed

README.md

+4-158
Original file line numberDiff line numberDiff line change
@@ -2,164 +2,10 @@
22

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

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

7-
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.
8-
The full list of integrations is available on our [Marketplace](https://www.rapid7.com/marketplace/).
7+
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).
98

10-
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 `IntegrationAlliance@rapid7.com`.
11-
Please note that GitHub Issues are unmonitored by Rapid7 developers and are disabled for this repository.
9+
## Contributing
1210

13-
### Table of Contents
14-
15-
1. [Getting Started](#getting-started)
16-
2. [Example](#example)
17-
3. [Plugin Support](#plugin-support)
18-
4. [Contributing](#contributing)
19-
20-
### Getting Started
21-
22-
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.
23-
24-
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.
25-
26-
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.
27-
28-
Dependencies:
29-
30-
* [Python 3](https://www.python.org/download/releases/3.0/)
31-
* [Make](https://www.gnu.org/software/make/)
32-
* [Docker Engine](https://www.docker.com)
33-
* [InsightConnect plugin tooling](https://docs.rapid7.com/insightconnect/getting-started/)
34-
* [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/`.
35-
* [Pre-commit](https://pre-commit.com/) and [Black](https://github.com/psf/black)
36-
37-
For a quick & easy way to install tooling dependencies, run `update-tools.sh` from the `tools/` directory in this repository!
38-
39-
### Example
40-
41-
![Make Menu](./.github/make_menu_example.png)
42-
43-
Let's build and run a plugin from this repository.
44-
45-
We'll use the Dig plugin as an example. Dig is a command-line network utility for DNS.
46-
47-
```
48-
$ cd dig
49-
$ make
50-
[*] Use ``make menu`` for available targets
51-
[*] Including available Makefiles: ../tools/Makefiles/Colors.mk ../tools/Makefiles/Helpers.mk
52-
--
53-
[*] Building plugin image
54-
docker build --pull -t rapid7/dig:1.0.1 .
55-
Sending build context to Docker daemon 208.9kB
56-
Step 1/14 : FROM komand/python-3-37-slim-plugin:3
57-
2: Pulling from komand/python-3-37-slim-plugin
58-
Digest: sha256:74c67981efc06a27c0e650bc0bc3a681c87bc193869a3316945480c26371f7f4
59-
Status: Image is up to date for komand/python-3-37-slim-plugin:3
60-
...
61-
```
62-
63-
Now, let's create the runner script and then run the plugin:
64-
65-
```
66-
$ make runner
67-
[*] Use ``make menu`` for available targets
68-
[*] Including available Makefiles: ../tools/Makefiles/Colors.mk ../tools/Makefiles/Helpers.mk
69-
--
70-
[*] Creating link to run.sh |
71-
72-
$ ./run.sh -R tests/search_by_domain.json -j
73-
74-
Running: cat tests/forward.json | docker run --rm -i rapid7/dig:1.0.1 run | grep -- ^\{ | jq -r '.body | try(.log | split("\n") | .[]),.output'
75-
rapid7/Dig:1.0.1. Step name: forward
76-
Executing command /usr/bin/dig google.com A
77-
78-
{
79-
"status": "NOERROR",
80-
"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",
81-
"question": "google.com",
82-
"all_answers": [
83-
"172.217.12.174"
84-
],
85-
"last_answer": "172.217.12.174",
86-
"answer": "172.217.12.174",
87-
"nameserver": "192.168.65.1"
88-
}
89-
```
90-
91-
You can also run the plugin container in the background as a REST server:
92-
93-
```
94-
$ ./run.sh -c http
95-
Forwarding to port 10001
96-
Running: docker run --rm -d -p 10001:10001 -i rapid7/dig:1.0.1 http
97-
d719d45e9238d407010e656209f11b30674c2a3dd39225e232685737b111cc2d
98-
```
99-
100-
Let's run the equivalent of the previous example but with a web request:
101-
102-
```
103-
$ curl -d @tests/forward.json http://127.0.0.1:10001/actions/forward
104-
{
105-
"body": {
106-
"log": "rapid7/Dig:1.0.1. Step name: forward\nExecuting command /usr/bin/dig google.com A\n",
107-
"meta": {},
108-
"output": {
109-
"all_answers": [
110-
"172.217.9.78"
111-
],
112-
"answer": "172.217.9.78",
113-
"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",
114-
"last_answer": "172.217.9.78",
115-
"nameserver": "192.168.65.1",
116-
"question": "google.com",
117-
"status": "NOERROR"
118-
},
119-
"status": "ok"
120-
},
121-
"type": "action_event",
122-
"version": "v1"
123-
}
124-
```
125-
126-
You can generate sample JSON to use to test your plugin with the runner `run.sh`:
127-
128-
```
129-
$ ./run.sh -c sample
130-
Actions: [forward reverse]
131-
Triggers: []
132-
Sample requires sample name e.g. ``./run.sh -c sample <name>''
133-
134-
$ ./run.sh -c sample forward
135-
Running: docker run --rm -i rapid7/dig:1.0.1 sample forward | jq '.'
136-
{
137-
"body": {
138-
"action": "forward",
139-
"input": {
140-
"query": "A",
141-
"domain": "",
142-
"resolver": ""
143-
},
144-
"connection": null,
145-
"meta": {}
146-
},
147-
"version": "v1",
148-
"type": "action_start"
149-
}
150-
```
151-
152-
You can also generate all samples for a plugin with this shorthand: `./run.sh -c samples`
153-
154-
### Plugin Support
155-
156-
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).
157-
158-
```
159-
$ grep '^support:' microsoft_teams/plugin.spec.yaml
160-
support: community
161-
```
162-
163-
### Contributing
164-
165-
See our [contributing guide](./CONTRIBUTING.md).
11+
Please see our [contribution guide](./CONTRIBUTING.md) for contributing changes back to this repository.

0 commit comments

Comments
 (0)