|
2 | 2 |
|
3 | 3 | [](https://github.com/psf/black)
|
4 | 4 |
|
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. |
6 | 6 |
|
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). |
9 | 8 |
|
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 |
12 | 10 |
|
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 |
| - |
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