README.md

Writing plugins for CHIRP

---

Requirements

At minimum each new plugin should add two files: __init__.py and a file that contains the plugin logic. There are extra actions that must be taken if trying to compile CHIRP. See more in the Known Issues section below.

__init__.py

REQUIRED

• A variable named entrypoint, with the value being the plugin's main function. WHICH MUST BE ASYNCHRONOUS

OPTIONAL

• A variable named REQUIRED_OS, which can be a singular string value, tuple or list. Acceptable parameters are Windows, MacOS, and Linux. If REQUIRED_OS is not specified, will run on any OS.
• A variable named REQUIRED_ADMIN, which accepts a bool value. If this value is true, the plugin will only run in an admin console. If REQUIRED_ADMIN is not specified, will run in any context.

EXAMPLE

From chirp.plugins.events.__init__

from . import __scan__        # Import the file containing our main function

REQUIRED_OS = "Windows"       # Specify this will only run on Windows
REQUIRED_ADMIN = True         # Specify this required administrator privileges
entrypoint = __scan__.run     # Set `entrypoint` to `__scan__.run` function.

Entrypoint

The entrypoint of the plugin must only accept one parameter, indicators, which is a dict-toolbox NameSpaceDict. This data is generated by our indicator loading method and has a specific format at the head:

{
    indicator_name {
        description: a description of the ioc,
        confidence: an integer indicating fidelity of the ioc,
        ioc_type: the name of your plugin,
        indicator: {
            ...
        }
    }
    second_indicator_name {
        ...
    }
    third_indicator_name {
        ...
    }
}

The values underneath indicator are entirely up to the plugin author. However, with this json input a plugin should be able to run their logic and provide useful output.

Optional Helpers

CHIRP provides multiple helper functions/capabilities to plugin authors.

Logging Methods

In chirp.common we have multiple logging methods. These methods will or will not print out based on the log level set with -l/--log-level. They all accept some string input and print to the program log.

• INFO(): Precedes output with green [+]
• ERROR(): Precedes output with red [-]
• CRITICAL(): Precedes output with cyan [!]
• DEBUG(): Precedes output with yellow [?]
• CONSOLE(): Raw output to log output.

Typing

In chirp.common, a type (JSON) is added for JSON compatible data.

Report Output

In chirp.common, a method (build_report) is added to easily create JSON writeable output from indicators.

Given the first indicator in our example in Entrypoint, build_report outputs:

{
    indicator_name {
        description: a description of the ioc,
        confidence: an integer indicating fidelity of the ioc,
        matches: []
    }
}

Matches for an indicator can be easily appended to the matches list, then the report can be written out to a JSON file.

Operators

CHIRP adds various operations in chirp.plugins.operators. This is used by multiple plugins built in to CHIRP to search through data.

operators has a primary method, searcher, which expects 2 arguments and takes an optional third:

searcher(check_value: Any, item: Any, key: Any = None) -> Union[bool, None]

• check_value: A search string like "== Lobster Thermidor aux crevettes with a Mornay sauce, garnished with truffle pâté, brandy and a fried egg on top, and Spam." or "~= ([eE]gg)*.*([sS]pam).*(baked beans)*".
  • ==: Searches for an exact match to a given value.
  • !=: Opposite of ==.
  • ~=: Performs a regex.
• item: The item being queried. If given a structure like a dictionary it will iterate over the structure, starting at the key (if given).
• key: The key to begin searching at. This can also be a value like key.subkey.subsubkey, and searcher will recurse the structure until it reaches the final key before beginning the search. In the previous example, this search would start at subsubkey.

Known issues

For compilation there are currently some workarounds that have to be done:

• Plugins must be added to the import statement that starts at line 20 in chirp.run.
• Requirements need to be specified in setup.py.
• Plugins must be added under packages in setup.py.

Note: These issues are SPECIFICALLY for compilation. If you are running with python, plugins will run fine without these.