From d7a5f7eeb557b5d828a050eda1b2a420878dda20 Mon Sep 17 00:00:00 2001 From: Madelon D Date: Mon, 16 Sep 2024 15:42:01 +0200 Subject: [PATCH 1/3] Update create boefje docs --- .../development_tutorial/creating_a_boefje.md | 48 ++++++++++++++++--- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md b/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md index 65e4d750f1..45e70793a6 100644 --- a/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md +++ b/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md @@ -1,4 +1,38 @@ -# Creating a boefje +# Creating a Boefje + +There are two ways to create a Boefje. The first is to create your own Boefje in the backend. The second is to create it in the User Interface. + +## Creating a Boefje (variant) in the User Interface + +**Note:** Currently, only admins are able to create Boefjes in the UI. + +To create a new Boefje, go to the KAT-alogus. Here you will find the _'Add Boefje'_ button. +To create a variant of an existing Boefje, go to the Boefje detail page of the Boefje you would like to use as a template and press the 'Add variant' button. + +### Setup your Boefje + +You will be directed to the Setup page, where you can configure your Boefje. The following items can be filled in: + +| Field | Required | Explanation | +| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Container image | Yes | The name of the Docker image. For example: _'ghcr.io/minvws/openkat/nmap'_ | +| Name | Yes | Give your Boefje a suiting name. This name will be visible in the KAT-alogus | +| Description | No | A description of the boefje explaining in short what it can do. This will both be displayed inside the KAT-alogus and on the Boefje details page. | +| Arguments | No | For example: _'-sTU --top-ports 1000'_ | +| Json Schema | No | If any other settings are needed for your Boefje, add these as a JSON Schema, otherwise, leave the field empty or 'null'. This JSON is used as the basis for a form for the user. When the user enables this Boefje they can get the option to give extra information. For example, it can contain an API key that the script requires. | +| Input object type | No | Select the object type(s) that your Boefje consumes. | +| Output mime-types | No | Add a set of mime-types that are produced by this Boefje, separated by commas. For example: _'text/html'_, _'image/jpeg'_ or _'boefje/{boefje-id}'_. These output mime-types will be shown on the Boefje detail page as information for other users. | +| Clearance level | No | Select a clearance level for your Boefje, which indicates how deeply your Boefje can scan objects. | + +### Using your Boefje + +After finishing the setup and creating your Boefje, you can view it in the KAT-alogus. The Boefje detail page will show you all the information about your newly created Boefje. + +### Updating your Boefje + +To update your Boefje, you go to the _'Variants'_ section on the Boefje detail page. Expand the table row of the Boefje you want to change and press the _'Edit Boefje'_ button. + +## Creating a boefje in the code Inside `boefjes/boefjes/plugins/` create a new folder with a name starting with `kat_` for this example we use `kat_hello_katty` @@ -14,11 +48,11 @@ $ tree boefjes/boefjes/plugins/kat_hello_katty/ └── schema.json ``` -## `__init__.py` +### `__init__.py` This file stays empty. -## `boefje.json` +### `boefje.json` This file contains information about our boefje. For example, this file contains information about what OOIs our boefje should be looking out for. Here is the example we will be using: @@ -40,15 +74,15 @@ This file contains information about our boefje. For example, this file contains - **`scan_level`**: A scan level that decides how intrusively this boefje will scan the provided OOIs. Since we will not make any external requests our boefje will have a scan level of 0. - **`oci_image`**: The name of the docker image that is provided inside `boefjes/Makefile` -## `cover.jpg` +### `cover.jpg` This file has to be an image of the developer's cat. This image will be used as a thumbnail for the boefje. -## `description.md` +### `description.md` This file contains a description of the boefje to explain to the user what this boefje does. For this example we can leave this empty. -## `schema.json` +### `schema.json` To allow the user to pass information to a boefje runtime, add a schema.json file to the folder where your boefje is located. This can be used, for example, to add an API key that the script requires. @@ -104,7 +138,7 @@ Schema validation happens right before spawning a boefje, meaning your tasks wil - `NUMBER`: For this property we ask the user to send us an integer between 0 and 9. - `required`: In here we need to give a list of the objects' names that the user has to provide to run our boefje. For this example, we will only require the user to give us the `MESSAGE` variable. We do this by adding `"MESSAGE"` to the `required` list. -## `main.py` +### `main.py` This is the file where the boefje's meowgic happens. This file has to contain a run method that accepts a dictionary and returns a `list[tuple[set, bytes | str]]`. This function will run whenever a new OOI gets created with one of the types mentioned in `consumes` inside `boefje.json`. : From a4d7f20cfa5d100bab36b4f45437094e963c30bd Mon Sep 17 00:00:00 2001 From: Madelon D Date: Mon, 16 Sep 2024 15:55:16 +0200 Subject: [PATCH 2/3] Small changes to documentation --- .../development_tutorial/creating_a_boefje.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md b/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md index 45e70793a6..1a44d0b49f 100644 --- a/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md +++ b/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md @@ -1,13 +1,13 @@ # Creating a Boefje -There are two ways to create a Boefje. The first is to create your own Boefje in the backend. The second is to create it in the User Interface. +There are two ways to create a Boefje. The first is to create a Boefje with the User Interface (UI). The second option is to create it in the backend. ## Creating a Boefje (variant) in the User Interface **Note:** Currently, only admins are able to create Boefjes in the UI. -To create a new Boefje, go to the KAT-alogus. Here you will find the _'Add Boefje'_ button. -To create a variant of an existing Boefje, go to the Boefje detail page of the Boefje you would like to use as a template and press the 'Add variant' button. +To create a **new** Boefje, go to the KAT-alogus. Here you will find the _'Add Boefje'_ button. +To create a **variant** of an existing Boefje, go to the Boefje detail page of the Boefje you would like to use as a template and press the _'Add variant'_ button. ### Setup your Boefje @@ -16,17 +16,17 @@ You will be directed to the Setup page, where you can configure your Boefje. The | Field | Required | Explanation | | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Container image | Yes | The name of the Docker image. For example: _'ghcr.io/minvws/openkat/nmap'_ | -| Name | Yes | Give your Boefje a suiting name. This name will be visible in the KAT-alogus | -| Description | No | A description of the boefje explaining in short what it can do. This will both be displayed inside the KAT-alogus and on the Boefje details page. | +| Name | Yes | Give your Boefje a suiting name. This name will be visible in the KAT-alogus. | +| Description | No | A description of the Boefje explaining in short what it can do. This will both be displayed inside the KAT-alogus and on the Boefje details page. | | Arguments | No | For example: _'-sTU --top-ports 1000'_ | | Json Schema | No | If any other settings are needed for your Boefje, add these as a JSON Schema, otherwise, leave the field empty or 'null'. This JSON is used as the basis for a form for the user. When the user enables this Boefje they can get the option to give extra information. For example, it can contain an API key that the script requires. | -| Input object type | No | Select the object type(s) that your Boefje consumes. | +| Input object type | No | Select the object type(s) that your Boefje. consumes. | | Output mime-types | No | Add a set of mime-types that are produced by this Boefje, separated by commas. For example: _'text/html'_, _'image/jpeg'_ or _'boefje/{boefje-id}'_. These output mime-types will be shown on the Boefje detail page as information for other users. | | Clearance level | No | Select a clearance level for your Boefje, which indicates how deeply your Boefje can scan objects. | ### Using your Boefje -After finishing the setup and creating your Boefje, you can view it in the KAT-alogus. The Boefje detail page will show you all the information about your newly created Boefje. +After finishing the setup and creating your Boefje, you can view it in the KAT-alogus. The Boefje detail page will show you all the detailed information about your newly created Boefje. Both on the KAT-alogus as on the Boefje detail page, you can enable or disable your Boefje. ### Updating your Boefje From fa0c57886feeb6a76bb350cb7ce2d369b9013a1e Mon Sep 17 00:00:00 2001 From: Madelon D Date: Tue, 17 Sep 2024 17:01:56 +0200 Subject: [PATCH 3/3] Update documentation --- .../development_tutorial/creating_a_boefje.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md b/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md index 1a44d0b49f..be2569b928 100644 --- a/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md +++ b/docs/source/developer_documentation/development_tutorial/creating_a_boefje.md @@ -2,6 +2,10 @@ There are two ways to create a Boefje. The first is to create a Boefje with the User Interface (UI). The second option is to create it in the backend. +## Boefje variants + +Boefje variants are Boefjes that use the same container image. In OpenKAT, all Boefjes with the same container image will be seen as 'variants' of each other and will be shown together on those Boefje detail pages. + ## Creating a Boefje (variant) in the User Interface **Note:** Currently, only admins are able to create Boefjes in the UI. @@ -9,24 +13,24 @@ There are two ways to create a Boefje. The first is to create a Boefje with the To create a **new** Boefje, go to the KAT-alogus. Here you will find the _'Add Boefje'_ button. To create a **variant** of an existing Boefje, go to the Boefje detail page of the Boefje you would like to use as a template and press the _'Add variant'_ button. -### Setup your Boefje +### Set up your Boefje You will be directed to the Setup page, where you can configure your Boefje. The following items can be filled in: | Field | Required | Explanation | | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Container image | Yes | The name of the Docker image. For example: _'ghcr.io/minvws/openkat/nmap'_ | -| Name | Yes | Give your Boefje a suiting name. This name will be visible in the KAT-alogus. | +| Name | Yes | Give your Boefje a suitable name. This name will be visible in the KAT-alogus. | | Description | No | A description of the Boefje explaining in short what it can do. This will both be displayed inside the KAT-alogus and on the Boefje details page. | | Arguments | No | For example: _'-sTU --top-ports 1000'_ | | Json Schema | No | If any other settings are needed for your Boefje, add these as a JSON Schema, otherwise, leave the field empty or 'null'. This JSON is used as the basis for a form for the user. When the user enables this Boefje they can get the option to give extra information. For example, it can contain an API key that the script requires. | -| Input object type | No | Select the object type(s) that your Boefje. consumes. | +| Input object type | No | Select the object type(s) that your Boefje consumes. | | Output mime-types | No | Add a set of mime-types that are produced by this Boefje, separated by commas. For example: _'text/html'_, _'image/jpeg'_ or _'boefje/{boefje-id}'_. These output mime-types will be shown on the Boefje detail page as information for other users. | -| Clearance level | No | Select a clearance level for your Boefje, which indicates how deeply your Boefje can scan objects. | +| Clearance level | No | Select a clearance level for your Boefje, which indicates the clearance level the OOI's need before your Boefje will be scheduled on them. | ### Using your Boefje -After finishing the setup and creating your Boefje, you can view it in the KAT-alogus. The Boefje detail page will show you all the detailed information about your newly created Boefje. Both on the KAT-alogus as on the Boefje detail page, you can enable or disable your Boefje. +After finishing the setup and creating your Boefje, you can view it in the KAT-alogus for All Organizations in your OpenKAT-install. The Boefje detail page will show you all the detailed information about your newly created Boefje. Both on the KAT-alogus as on the Boefje detail page, you can enable or disable your Boefje. ### Updating your Boefje