Skip to content
This repository has been archived by the owner on Sep 20, 2023. It is now read-only.

Commit

Permalink
Proof-reading
Browse files Browse the repository at this point in the history
  • Loading branch information
Saad Kadhi committed Jul 31, 2018
1 parent 626984d commit 4a08e1d
Show file tree
Hide file tree
Showing 3 changed files with 37 additions and 42 deletions.
63 changes: 27 additions & 36 deletions api/how-to-create-a-responder.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,7 @@
* [Need Help?](#need-help)

## Writing a Responder
A responder is a program that takes JSON input and do an action and produces a basic result of that action.
It is made of at least 2 types of files:
A responder is a program that takes JSON input and do an action and produces a basic result of that action. Responders are very similar to analyzers though they have different purposes. Responders are made of at least 2 types of files:

- The program itself
- One or several service interaction files or flavors
Expand All @@ -31,32 +30,29 @@ written in Python.

### The Program
The first type of files a responder is made of is the core program that
performs actions. It can be written in any programming
language that is supported by Linux.
performs actions. It can be written in any programming language that is supported by Linux.

While many responders are written in Python (`*.py` files), you can write yours
in Ruby, Perl or even Scala. However, the very handy `Cortexutils` library
[described below](#the-cortexutils-python-library) is in Python. It greatly facilitates responder development and
you can write your responders in Python, Ruby, Perl or even Scala. However, the very handy `Cortexutils` library [described below](#the-cortexutils-python-library) is in Python. It greatly facilitates responder development and
it also provides some methods to quickly format the output to make it compliant
with the JSON schema expected by [TheHive](https://github.com/TheHive-Project/TheHive/).

### Service Interaction Files (Flavors)
A responder must have at least one service interaction file. Such files
contain key configuration information such as the responder's author
information, the datatypes (thehive:case, thehive:alert, ...) the responder accepts as
input, the TLP and PAP above which it will refuse to execute to protect against data
information, the datatypes (`thehive:case`, `thehive:alert`, ...) the responder accepts as
input and to which it applies to if used from TheHive, the TLP and PAP (or [Permissible Actions Protocol](https://www.misp-project.org/taxonomies.html#_pap)) above which it will refuse to execute to protect against data
leakage and to enforce sane OPSEC practices and so on.

A responder can have two or more service interaction files to allow it to
perform different actions. We speak then of flavors. For example, a mailer
responder can send message using several body template.
perform different actions. We speak then of flavors. For example, a Mailer
responder can send message using several body templates.

### Python Requirements
If the responder is written in Python, a `requirements.txt` must be provided
with the list of all the dependencies.

### Example: Mailer Responder Files
Below is a directory listing of the files corresponding to the Mailer
Below is a directory listing of the files corresponding to a Mailer
responder.

```bash
Expand All @@ -70,8 +66,7 @@ responders/Mailer
The input of a responder can be any JSON data, even a simple string. The submitter must send data with
the structure expected by the program. The acceptable datatypes described in the
Service Interaction files indicate what kind of data is expected.
For example, if the program requires a `thehive:case`, input must be comply with
TheHive case. Below an example of `thehive:case` input.
For example, if the program requires a `thehive:case` (i.e. it applies at the case level in TheHive), input must comply with TheHive case. Below an example of `thehive:case` input.

```json
{
Expand Down Expand Up @@ -113,10 +108,9 @@ TheHive case. Below an example of `thehive:case` input.
}
```

From the input send by the submitter, Cortex add `config` which is the responder's specific
configuration provided by org admin when the responder has been enabled.
In the addition to the input sent by the submitter, Cortex adds the `config` section which is the responder's specific configuration provided by an `orgAdmin` user when the responder is enabled in the Cortex UI.
#### Example: Service Interaction File for VirusTotal GetReport
#### Example: Service Interaction File for the Mailer Responder
The `<==` sign and anything after it are comments that do no appear in the
original file.
```json
Expand Down Expand Up @@ -194,28 +188,27 @@ various components and libraries you use if applicable.

#### description
Description of the responder. Please be concise and clear. The description is
shown in the Cortex UI, TheHive and MISP.
shown in the Cortex UI and TheHive.

#### dataTypeList
The list of TheHive datatypes supported by the responder. Currently TheHive
accepts the following datatypes:

- thehive:case
- thehive:case_artifact
- thehive:alert
- thehive:case_task
- thehive:log
- `thehive:case`
- `thehive:case_artifact` (i.e. observable)
- `thehive:alert`
- `thehive:case_task`
- `thehive:log` (i.e. task log)

#### baseConfig
Name used to group configuration items common to several responders. This
prevent the user to enter the same API key for all responder flavors.
The Cortex responder config page group configuration items by there baseConfig.
The Cortex responder config page group configuration items by their `baseConfig`.

#### config
Configuration dedicated to the responder's flavor. This is where we
typically specify the TLP level of observables allowed to be analyzed with the
`check_tlp` and `max_tlp` parameters. For example, if `max_tlp` is set to `2` (TLP:AMBER),
TLP:RED observables cannot be analyzed.
`check_tlp` and `max_tlp` parameters. For example, if `max_tlp` is set to `2` (TLP:AMBER), TLP:RED observables cannot be analyzed.
##### max_tlp
The TLP level above which the responder must not be executed.
Expand Down Expand Up @@ -301,14 +294,14 @@ If the responder **succeeds** (i.e. it runs without any error):
- `full` is the full report of the responder. It must contain at least
a message.
- `operations` is a list what the submitter system should execute.
Currently, TheHive accepts the following operations:
As of version 3.1.0, TheHive accepts the following operations:
- `AddTagToCase` (`{ "type": "AddTagToCase", "tag": "tag to add" }`): add
a tag to the case related to the object
The list of acceptable operation will increase in future release of TheHive.

The list of acceptable operations will increase in future releases of TheHive.

### The Cortexutils Python Library
So far, all the published responders have been written in Python. We
released a special Python library called `cortexutils` to help developers easily write their programs. Note though that Python is not mandatory for responder coding and any language that runs on Linux can be used, though you won't have the benefits of the CortexUtils library.
So far, all the published responders have been written in Python. We provide a Python library called `cortexutils` to help developers easily write their programs. Note though that Python is not mandatory for responder coding and any language that runs on Linux can be used, though you won't have the benefits of the CortexUtils library.
Cortexutils can be used with Python 2 and 3.
To install it :
Expand All @@ -324,8 +317,7 @@ pip3 install cortexutils
```
This library is already used by all the responders published in our [Github
repository](https://github.com/TheHive-Project/Cortex-Analyzers). Feel free to
start reading the code of some of them before writing your own.
repository](https://github.com/TheHive-Project/Cortex-Analyzers). Feel free to start reading the code of some of them before writing your own.
## Submitting a Responder
We **highly encourage you to share your responders** with the community through our Github repository. To do so, we invite you to follow a few steps before submitting a pull request.
Expand Down Expand Up @@ -387,12 +379,11 @@ If your responder is written in Python, make sure to complete the
needed to run the responder correctly.

### Verify Execution
Use these three simple checks before submtting your responder:
Use these three simple checks before submitting your responder:

- Ensure it works with the expecyed configuration, TLP or dataType.
- Ensure it works with missing configuration, dataType or TLP: your
- Ensure it works with the expected configuration, TLP, PAP or datatype.
- Ensure it works with missing configuration, PAP, datatype or TLP: your
responder must generate an explicit error message.
- Ensure the long report template handles error messages correctly.

### Create a Pull Request
Create one Pull Request per responder against the **develop** branch of the
Expand Down
7 changes: 3 additions & 4 deletions api/how-to-create-an-analyzer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,7 @@ with the JSON schema expected by [TheHive](https://github.com/TheHive-Project/Th
An analyzer must have at least one service interaction file. Such files
contain key configuration information such as the analyzer's author
information, the datatypes (IP, URL, hash, domain...) the analyzer accepts as
input, the TLP and PAP above which it will refuse to execute to protect against data
leakage and to enforce sane OPSEC practices and so on.
input, the TLP and PAP ([Permissible Actions Protocol](https://www.misp-project.org/taxonomies.html#_pap)) above which it will refuse to execute to protect against data leakage and to enforce sane OPSEC practices and so on.

An analyzer can have two or more service interaction files to allow it to
perform different actions. We speak then of flavors. For example, a sandbox analyzer can analyze a file with or without an
Expand Down Expand Up @@ -102,7 +101,7 @@ pieces of information. For example, to use the VirusTotal analyzer's
`data`, `dataType` and `tlp` are the observable-related information generated by
TheHive or any other program that is calling Cortex. `config` is the
analyzer's specific configuration provided by org admin when the analyzer has been enabled.
analyzer's specific configuration provided by an `orgAdmin` users when the analyzer is enabled in the Cortex UI.

Let's take the **GetReport** flavor of the VirusTotal analyzer as an
example again.
Expand Down Expand Up @@ -229,7 +228,7 @@ If you need additional datatypes for your analyzer, please let us know at
#### baseConfig
Name used to group configuration items common to several analyzer. This
prevent the user to enter the same API key for all analyzer flavors.
The Cortex analyzer config page group configuration items by there baseConfig.
The Cortex analyzer config page group configuration items by their `baseConfig`.

#### config
Configuration dedicated to the analyzer's flavor. This is where we
Expand Down
9 changes: 7 additions & 2 deletions installation/install-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ yum install cortex
Once the package is installed, [install the analyzers](#analyzers-1) as outlined in the next section and proceed to the configuration using the [Quick Start Guide](../admin/quick-start.md). For more advanced configuration options, please refer to the [Administration Guide](../admin/admin-guide.md).

#### Pre-release versions
The RPM release package install two repositories `thehive-project-stable` and `thehive-project-beta`. The latter contains pre-release version and is disabled by default. If you want to install them and help us to find bugs, you can enable the repository by editing `/etc/yum.repos.d/thehive-rpm.repo` and set `enable` value to `1` for `thehive-project-beta` repository.
The RPM release package installs two repositories: `thehive-project-stable` and `thehive-project-beta`. The latter contains pre-release, beta versions and is disabled by default. If you want to install them and help us find bugs to the benefit of the whole community, you can enable it by editing `/etc/yum.repos.d/thehive-rpm.repo` and set `enable` value to `1` for `thehive-project-beta` repository.

### DEB
Debian packages are published on a Bintray repository. All packages are signed using our GPG key [562CBC1C](https://raw.githubusercontent.com/TheHive-Project/Cortex/master/PGP-PUBLIC-KEY). Its fingerprint is:
Expand All @@ -73,7 +73,7 @@ Some environments may block access to the `pgp.mit.edu` key server. As a result,
Once the package is installed, [install the analyzers](#analyzers-1) as outlined in the next section and proceed to the configuration using the [Quick Start Guide](../admin/quick-start.md). For more advanced configuration options, please refer to the [Administration Guide](../admin/admin-guide.md).

#### Pre-release versions
If you want to install pre-release version of packages and help us to find bugs, you can add the pre-release repository with the command:
If you want to install pre-release, beta versions of TheHive packages and help us find bugs to the benefit of the whole community, you can add the pre-release repository with the command:
```bash
echo 'deb https://dl.bintray.com/thehive-project/debian-beta any main' | sudo tee -a /etc/apt/sources.list.d/thehive-project.list
```
Expand Down Expand Up @@ -172,6 +172,9 @@ Analyzers are embedded in the docker image under `/opt/Cortex-Analyzers/analyzer
#### What to Do Next?
Once the Docker image is up and running, proceed to the configuration using the [Quick Start Guide](../admin/quick-start.md). For more advanced configuration options, please refer to the [Administration Guide](../admin/admin-guide.md).

#### Pre-release Versions
If you would like to use pre-release, beta versions of our Docker images and help us find bugs to the benefit of the whole community, please use `thehiveproject/cortex:version-RCx`. For example `thehiveproject/cortex:2.1.0-RC1`.

### Binary
The following section contains the instructions to manually install Cortex using binaries on **Ubuntu 16.04 LTS**.

Expand Down Expand Up @@ -222,6 +225,8 @@ unzip cortex-latest.zip
ln -s cortex-x.x.x cortex
```

**Note**: if you would like to use pre-release, beta versions of and help us find bugs to the benefit of the whole community, please download `https://dl.bintray.com/thehive-project/binary/cortex-version-RCx.zip`. For example `https://dl.bintray.com/thehive-project/binary/cortex-2.1.0-RC1.zip`.

#### 5. First start
It is recommended to use a dedicated, non-privileged user account to start Cortex. If so, make sure that the chosen account can create log files in `/opt/cortex/logs`.

Expand Down

0 comments on commit 4a08e1d

Please sign in to comment.