Administrator

An administrator has access to everything a user has, and a few other functionalities:

The administrator home page

They can:

Manage the channels
Manage the users
Manage the schedulers

Settings

The settings page allows the administrator to manage the existing channels and create new ones. The channels used are using Redis, and require a name, a database number, a host (default redis) and a port (default 6379).

Users

The users page allows the administrator to:

Remove existing users,
Create or edit a scheduler,
Create a new user

Create a new administrator using CLI

If there is a need for multiple administrators, a new administrator can be created using the shell inside the API container (see the production installation for more details) using the following command:

../docker-entrypoint.sh create-user [USERNAME] [PASSWORD] --admin

Replacing [USERNAME] and [PASSWORD] with the corresponding data. Removing the --admin option will create a simple user, and adding --scheduler will create a new scheduler.

There are also two other commands that can be used in the CLI:

../docker-entrypoint.sh delete-user [USERNAME]

Will remove a user, no matter their role (admin, scheduler or user).

../docker-entrypoint.sh reset-password [USERNAME] [NEW_PASSWORD]

Will change the password of a user.

Add a new extern API

ℹ️

Please note that adding a new extern API requires to use the development environment and to rebuild the docker images after, to be using it in production environment.

If you need to add other externs APIs, it can be done this way:

Add API data in the database

First, you need to gather the data of the api you want to add, and insert it in the /passiveDNS/db/extern_apis.yml document as follows:

extern_apis.yml

...
---
  _key: "API_NAME"
  base_url: "BASE_URL"
  header: "NAME_OF_APIKEY_HEADER"
  ip: 
      method: "GET/POST"
      uri: "URI_FOR_IP_REQUEST"
  domain: 
      method: "GET/POST"
      uri: "URI_FOR_DOMAIN_REQUEST"

Replacing each line with the appropriate data. This data will automatically be added to the database the next time you run the application.

Add data formatting

Next, you need to update the /passiveDNS/analytics/extern_api.py file, to add the data formatting for your new API. To do so, you can get inspiration from the Virustotal or AlienVault formatting already existing.

There are 3 things to modify in this file :

First, add a global variable with the name you specified as _key in the .yml file.

extern_apis.yml

 9
10
11
12
13
...
VIRUSTOTAL_API = "VirusTotal"
ALIENVAULT_API = "AlienVault"
NEW_API = "API_NAME"
...

Then, you need to add the formatting function for you new API, at the end of the file:

extern_apis.yml

127
128
129
130
131
132
133
134
135
...
    #New API formatting
    def __formatNEW(self, response):
        #Add the formatting of the response based on the other formatting functions.

        ...

        return out
...

ℹ️

Note : The data returned should be a list with this format after passing through the function :

[
    {
        "domain_name": ,
        "ip_address": ,
        "first_updated_at": ,
        "last_updated_at": ,
    },
    "..."
]

Finally, in get_api function:

extern_apis.yml

74
75
76
77
78
79
80
81
...
    def get_api(self, api_name: str):
        __MAPPING = {VIRUSTOTAL_API: self.__formatVT, ALIENVAULT_API: self.__formatAV, NEW_API: self.__formatNEW}

        assert api_name in __MAPPING

        return __MAPPING[api_name]
...

User guide Scheduler