CSAF-Netbox-Plugin

Configuration

It is important to add the csaf plugin before the d3c plugin in the Netbox configuration:

PLUGINS = ["csaf","d3c"]

The following options must be configured as well:

PLUGINS_CONFIG = {
  'csaf': {
    'isduba': {
      'keycloak_url': 'http://keyCloak.my.domain/', # Base URL of KeyCloak used by IsDuBa
      'keycloak_verify_ssl': False, # Should SSL errors be thrown (True) or ignored (False).
      'document_verify_ssl': False, # Should SSL errors be thrown (True) or ignored (False) when downloading CSAF documents.
      'document_retry_interval_minutes': 60, # Minutes between retries for failed CSAF document downloads.
      'username': 'MyUserName', # user name for KeyCloak
      'password': 'MyPassword' # user password for KeyCloak
    },
    'synchronisers': {
      'username': '<user name for synchronisers/matchers>', # Can be overridden for individual Synchronisers.
      'password': '<password for synchronisers/matchers>', # Can be overridden for individual Synchronisers.
      'verify_ssl': False, # Should SSL errors be thrown (True) or ignored (False). Can be overridden for individual Synchronisers.
      'urls': [ # The list of Synchronisers and Matchers
        {
          'name': 'ISDuBA Sync', # The display name of the Synchoniser.
          'url': 'http://127.0.0.1:8991/' # The URL that Netbox can use to reach the Synchoniser.
        },
        {
          'name': 'Netbox Sync', # The display name of the Synchoniser.
          'url': 'http://127.0.0.1:8992/' # The URL that Netbox can use to reach the Synchoniser.
        },
        {
          'name': 'CSAF Matcher', # The display name of the Matcher.
          'url': 'http://127.0.0.1:8998/', # The URL that Netbox can use to reach the matcher.
          'isMatcher': True,  # Set to True if this is a Matcher, empty or False for Synchronisers.
          'netboxBaseUrl': 'http://localhost:8000', # The base URL of Netbox as the Matcher sees it.
          'isdubaBaseUrl': 'http://localhost:5371',  # The base URL of ISDuBA as the Matcher sees it.
        },
      ]
    }
  }
}

The username and password for Synchronisers and Matcher can be overridden on a per-matcher basis. The netboxBaseUrl of the CSAF Matcher must be set to the url of Netbox as the Matcher sees it.

User Rights

For controlling synchronisers and matchers additional rights are required for non-admin users. These must be added as Additional actions on the Netbox CSAF|csaf match Object type.

• viewSynchronisers: Access the Synchronisers page.
• startSynchronisers: Start synchronisers and Matcher tasks.
• stopSynchronisers: Stop synchronisers and Matcher tasks.
• clearSynchronisers: Clear the cache database of the Matcher.

An example of these additional actions is in the image below:

Installation of the CSAF Plugin

As the CSAF plugin is a standard NetBox plugin, it can be installed according to the NetBox documentation. This plugin is compatible with NetBox version 4.3.1.

This plugin depends on the DDDC Plugin.

Adding the plugin to an existing netbox-docker installation

Set the proper netbox docker version

The CSAF Plugin is only compatible with NetBox 4.3 and therefore with netbox-docker 3.2.1. For a new install, clone from tag 3.2.1:

git clone -b 3.2.1 https://github.com/netbox-community/netbox-docker.git

For existing installations, switch to tag 3.2.1 before continuing:

git checkout 3.2.1

Add plugin

The Plugin can be added to any existing or new setup of netbox-docker by following their plugin instructions.

1. Create the file plugin_requirements.txt with the following content:

   git+https://github.com/DINA-community/DDDC-Netbox-plugin.git
   git+https://github.com/DINA-community/CSAF-Netbox-Plugin.git

2. Create the file Dockerfile-Plugins with the content from the netbox-docker documentation. Add this snippet before the line RUN /usr/local/bin/uv pip:

   RUN apt-get update && DEBIAN_FRONTEND="noninteractive" apt install -y git

   Also, replace

   FROM netboxcommunity/netbox:latest

   with

   FROM netboxcommunity/netbox:v4.3-3.3.0

   Matching the version of netbox-docker.

3. Create the file docker-compose.override.yml with the content from the netbox-docker documentation.

   You can also create a superuser by adding these lines with meaningful values. Alternatively, create the superuser in step 6.

         environment:
            SKIP_SUPERUSER: "false"
            #SUPERUSER_API_TOKEN: ""
            SUPERUSER_EMAIL: ""
            SUPERUSER_NAME: ""
            SUPERUSER_PASSWORD: ""

   Also, change the image versions

      image: netbox:v4.3-3.3.0

   for all services

4. Add this to configuration/plugins.py:

   PLUGINS = ["csaf", "d3c"]

   You can also add a section PLUGINS_CONFIG for d3c and csaf here. See above for the configuration example.

5. Build and run it (see Troubleshoot):

   docker compose build --no-cache
   docker compose up -d

6. Access your local netbox by http://127.0.0.1:8000. To create an admin user, run this command:

   docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

Notes regarding the installation of this plugin via the provided files

The installation will provide a warning message since the installation is using the default security token:

⚠️ Warning: You have the old default admin token in your database. This token is widely known; please remove it.

In theory, you can add an alternative security token in the file netbox.env by adding the following line:

SUPERUSER_API_TOKEN=<Token>

However, an important aspect of an installation in a production environment is the creation of users, tokens, and their permissions. This must be done for each NetBox installation separately and in accordance with the specific requirements in place.

Help

This section contains links for familiarizing yourself with Django, NetBox, and plugins.

General

• Installation of NetBox as a standalone, self-hosted application: https://docs.netbox.dev/en/stable/installation/
• Community driven Docker image for netbox: https://github.com/netbox-community/netbox-docker
• Using NetBox Plugins in Docker: https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins

Development

• Official plugin development documentation of NetBox: https://docs.netbox.dev/en/stable/plugins/development/
• NetBox plugin development Tutorial: https://github.com/netbox-community/netbox-plugin-tutorial
• Setting up a development environment with Docker for NetBox plugins: netbox-community/netbox-docker#746
• django-table2 Documentation used by the Plugin and NetBox: https://django-tables2.readthedocs.io/en/latest/