Project

General

Profile

Agent Registration

Table of Contents

As of libprelude 0.9.15, prelude-adduser is deprecated. Please now use prelude-admin, as specified in the documentation.

Registration

In order for an agent to connect and communicate with a _Prelude-Manager', it needs to be registered. Registration involves several steps:

  • Allocating an unique identity for the sensor
  • Creating directory to be used by the sensor (example: failover purpose)
  • Registering to a remote Prelude-Manager: get a signed X509 certificate that will allows communication between sensor and manager using the specified permissions.

All these informations are stored in a sensor 'profile'.

Profile

A sensor profile is identified by its name. When a sensor is started, it will try to load a profile of the same name as the program itself, that is, if your sensor is named "prelude-lml", the sensor will try to load a profile named "prelude-lml".

The name of the profile can be overriden using the --prelude --profile name_of_my_profile command line option. We provide the ability of defining the profile name so that you can have multiples instances of one sensor running with different permissions, which require different profiles.

Note that profiles are not specific to sensor, but are used in all programs of the Prelude suite (sensors, managers, etc).

Agent Registration / Profile Creation

The agent registration process is driven by a single tool called prelude-admin.

   $ prelude-admin register <profile name> <requested permission> <manager address> --uid <uid> --gid <gid>

Replace <profile name> with the name of the sensor you are installing, or with your own defined name if you want more advanced sensor profile control. If you start your sensor without it being registered, it will show you a warning including the default profile name to be used for registering the sensor.

Remember to use the correct uid/gid when registering your sensor. For instance, if you want to register snort (running with snort euid / egid), use --uid snort --gid snort. If the sensor process cannot read the created profiles information (key, cert...), you will get an error and the sensor will refuse to start.

The first time an agent is registered, prelude-admin will need to create a private key for the agent. Under Linux, the operation can take a very long time due to the entropy generation system: advises on fixing this problem are available on the Misc/Entropy page.

Requested Permission

Replace <requested permission> with the permission your sensor needs. There are several kind of permission:
  • idmef
  • admin

Both idmef and admin type can take read (r) and write (w) permission. Usually, a sensor need permission of writing IDMEF messages to a manager, and optionally accept administrative command sent to the sensors. That is : idmef:w admin:r.

Note: If you are not sure which permission your sensor should get, just start the sensor, which should then provide you with the prelude-admin options to use for registration.

Manager Addresses

You should replace the <manager address> argument by the address where the prelude-manager you wish to register to is running, this can either be its IP address or its hostname name. Typically, if you made a local installation, you can write localhost there.

You need to repeat this step for each manager you want to register the sensor.
When you are not sure about how your sensor should be registered, just start the sensor, which should then provide you with the prelude-admin options to use for registering it:

prelude-client-profile: error creating prelude-client: Could not open [[AnalyzerID]] file.

Basic file configuration does not exist. Please run :
prelude-admin register prelude-lml "idmef:w admin:r" <manager address> --uid 1000 --gid 100
program to setup the analyzer.

Be aware that you should replace the "<manager address>" argument with
the server address this analyzer is reporting to as argument.
"prelude-admin" should be called for each configured server address.

The default is to create the sensor profile using the UID and GID of the user who launched the prelude-admin command. If you want the profile to be run by another set of permission, use the --uid and --gid options.

Prelude-LML Registration example

This is an example on registering Prelude-LML on host lmlhost to a Prelude-Manager running on host managerhost:

$ prelude-admin register prelude-lml "idmef:w admin:r" *managerhost*
Generating 1024 bits RSA private key... This might take a very long time.
[Increasing system activity will speed-up the process].
Generation in progress... X

Note: The first time an agent is registered, prelude-admin will need to create a private key for the agent. Under Linux, the operation can take a very long time due to the entropy generation system: advises on fixing this problem are available on the Misc/Entropy page.

prelude-admin will then ask you to start another prelude-admin instance on the machine where the prelude-manager server is listening (managerhost in this example).

You now need to start "prelude-admin" registration-server on managerhost:
example: "prelude-admin registration-server prelude-manager" 

Enter the one-shot password provided on managerhost: 

On managerhost, you now need to start prelude-admin registration-server command using the profile name used by your Prelude-Manager:

   $ prelude-admin registration-server prelude-manager

The "deadbeaf" password will be requested by "prelude-admin register" 
in order to connect. Please remove the quotes before using it.

Generating 1024 bits Diffie-Hellman key for anonymous authentication...++++++++++.+++++..++++++++++
Waiting for peers install request on 0.0.0.0:5553...

As you can see, the generated password is deadbeaf. You need to enter this password in the lmlhost prelude-admin session:

Enter the one-shot password provided on localhost: [you don't see this, but deadbeaf is typed]
Confirm the one-shot password provided on localhost: [you don't see this, but deadbeaf is typed]

Connecting to registration server (localhost:5553)... Authentication succeeded.
Successful registration to localhost:5553.

This is what you'll get on the server side:

Connection from 127.0.0.1:52507...

Registration request for analyzerID="229348179011709" permission="idmef:w admin:r".
Approve registration? [y/n]: y
127.0.0.1:52507 successfully registered.

The operation was successful! congratulations, you now have a sensor up and running.