Project

General

Profile

How to use LibPrelude » History » Version 2

Anonymous, 05/07/2015 12:52 PM

1 1 Anonymous
h1. How to use LibPrelude
2 1 Anonymous
3 1 Anonymous
This tutorial is meant to explain how the library LibPrelude works, what differs in LibPrelude from the original IDMEF and to give a few examples on how to implement it.
4 1 Anonymous
5 1 Anonymous
h2. What is LibPrelude ?
6 1 Anonymous
7 1 Anonymous
LibPrelude is the first and only implementation of IDMEF. It is used as a mean of communication between Prelude modules. Prelude is a SIEM developed by C-S, which takes part in the SECEF project. Since part of Prelude is open-source, LibPrelude is also open-source and can be used freely.
8 1 Anonymous
As Prelude uses LibPrelude as a mean of communication between modules, LibPrelude is designed to send IDMEF alerts to a Prelude Manager and can't be used, as for now, without one.
9 1 Anonymous
LibPrelude is written in C, but you canfind bindings for Python, Perl, C++, Ruby and Lua. We will give example on how to use it below, but you can also find it on "Prelude's site":https://www.prelude-siem.org/projects/prelude/wiki/DevelAgentBuilding.
10 1 Anonymous
11 1 Anonymous
h2. Download and install
12 1 Anonymous
13 1 Anonymous
You can install libprelude from the repositories on most distributions using :
14 1 Anonymous
* Debian : 
15 1 Anonymous
<pre>
16 1 Anonymous
apt-get install libprelude-dev
17 1 Anonymous
</pre>
18 1 Anonymous
* CentOS : 
19 1 Anonymous
<pre>
20 1 Anonymous
rpm -i https://www.prelude-ids.org/attachments/download/297/prelude-ids-rhel-2-1.noarch.rpm
21 1 Anonymous
yum install libprelude
22 1 Anonymous
</pre>
23 1 Anonymous
24 1 Anonymous
You can also find the packages on "Prelude's site":https://www.prelude-siem.org/projects/prelude/files.
25 1 Anonymous
26 1 Anonymous
h2. How does it work ?
27 1 Anonymous
28 1 Anonymous
LibPrelude is a library that allows you to send IDMEF alerts to a Prelude manager. It is, however, impossible to just create IDMEF alerts and export it in a readable format. 
29 1 Anonymous
30 1 Anonymous
To send IDMEF alerts to a Prelude Manager, you first have to create a client. This client will be the one sending alerts to the manager. And to do so, it will need to registrate to the Prelude Manager.
31 1 Anonymous
32 1 Anonymous
The client will send heartbeats to the manager, stating that he is still alive and well, and, whenn needed, send alerts the exact same way.
33 1 Anonymous
Note that heartbeats are also IDMEF messages.
34 1 Anonymous
35 2 Anonymous
Using LibPrelude to send alerts to prelude manager can be done in several steps : 
36 2 Anonymous
* Initializing the Prelude Library
37 2 Anonymous
* Creating the Prelude Client
38 2 Anonymous
* Starting the Prelude Client : This will make it send heartbeats at a regular pace
39 2 Anonymous
* Creating alerts
40 2 Anonymous
* Sending Alerts
41 2 Anonymous
42 1 Anonymous
h2. Format
43 1 Anonymous
44 1 Anonymous
LibPrelude is based an IDMEF. However, it does not completely follow what is indicated in the RFC 4735.
45 1 Anonymous
First, LibPrelude does not use XML encoding format, as it is strongly suggested in the RFC. This means that some attributes, such as alertident, are slightly modified from the RFC. But we can also find differences on how to interprete some of the IDMEF fields.
46 1 Anonymous
You can add multiple analyzers for one alert using LibPrelude, whereas it's a single required field in the RFC. This difference come from the fact that the RFC and LibPrelude don't have the same definition of an analyzer. LibPrelude sees as an analyzer every tool that participated in creating the alert. 
47 1 Anonymous
48 1 Anonymous
49 2 Anonymous
h2. First steps with LibPrelude in several languages
50 1 Anonymous
51 2 Anonymous
This section is just meant to give a brief overview of how to use LibPrelude. If you really want to build a new sensor, please refer to the [[Building a new Sensor]] section.
52 2 Anonymous
53 1 Anonymous
h3. Using C
54 2 Anonymous
55 2 Anonymous
LibPrelude being originally written in C, you will have more choice using C than other languages.
56 2 Anonymous
First, you will have to choose between using the low level API or the high level API. Using the low level API, as you would imagine, gives more performance, but needs more lines and is less intuitive. It also needs less memory. The high level API, indeed, creates a whole alerts, with every field already existing, everytime you create a new alert, whereas the low level API needs field to be created one by one.
57 2 Anonymous
58 2 Anonymous
Let's take a brief look at these API.
59 2 Anonymous
60 2 Anonymous
h4. Low level API
61 2 Anonymous
62 2 Anonymous
* Initializing the Prelude Library
63 2 Anonymous
64 2 Anonymous
<pre><code class="c">
65 2 Anonymous
66 2 Anonymous
#include <libprelude/prelude.h> 
67 2 Anonymous
68 2 Anonymous
int ret;
69 2 Anonymous
70 2 Anonymous
ret = prelude_init(&argc, argv);
71 2 Anonymous
if ( ret < 0 ) {
72 2 Anonymous
        prelude_perror(ret, "unable to initialize the prelude library");
73 2 Anonymous
        return -1;
74 2 Anonymous
}
75 2 Anonymous
</code></pre>
76 2 Anonymous
77 2 Anonymous
* Creating a new prelude client
78 2 Anonymous
79 2 Anonymous
<pre><code class="c">
80 2 Anonymous
int ret;
81 2 Anonymous
prelude_client_t *client;
82 2 Anonymous
83 2 Anonymous
ret = prelude_client_new(&client, "my-analyzer");
84 2 Anonymous
if ( ! client ) {
85 2 Anonymous
        prelude_perror(ret, "Unable to create a prelude client object");
86 2 Anonymous
		
87 2 Anonymous
		/*This suppresses the client in case it was created but still sending errors*/
88 2 Anonymous
		prelude_client_destroy(client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS);
89 2 Anonymous
        return -1;
90 2 Anonymous
}
91 2 Anonymous
</code></pre>
92 2 Anonymous
93 2 Anonymous
* Starting a new client
94 2 Anonymous
95 2 Anonymous
<pre><code class="c">
96 2 Anonymous
ret = prelude_client_start(client);
97 2 Anonymous
if ( ret < 0 ) {
98 2 Anonymous
		prelude_perror(ret, "Unable to start prelude client");
99 2 Anonymous
	   
100 2 Anonymous
	   	/*This suppresses the client in case something went wrong*/
101 2 Anonymous
		prelude_client_destroy(client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS);
102 2 Anonymous
		return -1;
103 2 Anonymous
}
104 2 Anonymous
</code></pre>
105 2 Anonymous
106 2 Anonymous
* Setting client options
107 2 Anonymous
108 2 Anonymous
<pre><code class="c">
109 2 Anonymous
ret = prelude_client_set_flags(prelude_client, PRELUDE_CLIENT_FLAGS_ASYNC_SEND|PRELUDE_CLIENT_FLAGS_ASYNC_TIMER);
110 2 Anonymous
if ( ret < 0) {
111 2 Anonymous
	fprintf(stderr, "Unable to set asynchronous send and timer.\n");
112 2 Anonymous
	
113 2 Anonymous
	/* This suppresses the client and avoid having a not configured client sending things */
114 2 Anonymous
	prelude_client_destroy(prelude_client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS); 
115 2 Anonymous
	return -1;
116 2 Anonymous
}
117 2 Anonymous
</code></pre>
118 2 Anonymous
119 2 Anonymous
* Creating the alert
120 2 Anonymous
121 2 Anonymous
<pre><code class="c">
122 2 Anonymous
idmef_message_t *idmef;
123 2 Anonymous
124 2 Anonymous
ret = idmef_message_new(&idmef);
125 2 Anonymous
if ( ret < 0 ) {
126 2 Anonymous
        prelude_perror(ret, "unable to create IDMEF message");
127 2 Anonymous
        return -1;
128 2 Anonymous
}
129 2 Anonymous
130 2 Anonymous
ret = idmef_message_new_alert(idmef, &alert);
131 2 Anonymous
if ( ret < 0 ) {
132 2 Anonymous
        prelude_perror(ret, "unable to create IDMEF alert");
133 2 Anonymous
        idmef_message_destroy(idmef);
134 2 Anonymous
        return -1;
135 2 Anonymous
}
136 2 Anonymous
137 2 Anonymous
ret = idmef_alert_new_classification(alert, &class);
138 2 Anonymous
if ( ret < 0 ) {
139 2 Anonymous
        prelude_perror(ret, "unable to create IDMEF classification");
140 2 Anonymous
        idmef_message_destroy(idmef);
141 2 Anonymous
        return -1;
142 2 Anonymous
}
143 2 Anonymous
144 2 Anonymous
ret = idmef_classification_new_text(class, &str);
145 2 Anonymous
if ( ret < 0 ) {
146 2 Anonymous
        prelude_perror(ret, "unable to create classification text");
147 2 Anonymous
        idmef_message_destroy(idmef);
148 2 Anonymous
        return -1;
149 2 Anonymous
}
150 2 Anonymous
151 2 Anonymous
prelude_string_set_constant(str, "My classification");
152 2 Anonymous
</code></pre>
153 2 Anonymous
154 2 Anonymous
* Sending the alert
155 2 Anonymous
156 2 Anonymous
<pre><code class="c">
157 2 Anonymous
prelude_client_send_idmef(client, idmef);
158 2 Anonymous
idmef_message_destroy(idmef);
159 2 Anonymous
</code></pre>
160 2 Anonymous
161 2 Anonymous
* Destroying the client
162 2 Anonymous
163 2 Anonymous
<pre><code class="c">
164 2 Anonymous
prelude_client_destroy(client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS);
165 2 Anonymous
</code></pre>
166 2 Anonymous
167 2 Anonymous
h4. High level API
168 2 Anonymous
169 2 Anonymous
* Initializing the Prelude Library
170 2 Anonymous
171 2 Anonymous
<pre><code class="c">
172 2 Anonymous
173 2 Anonymous
#include <libprelude/prelude.h>
174 2 Anonymous
175 2 Anonymous
int ret;
176 2 Anonymous
177 2 Anonymous
ret = prelude_init(&argc, argv);
178 2 Anonymous
if ( ret < 0 ) {
179 2 Anonymous
        prelude_perror(ret, "unable to initialize the prelude library");
180 2 Anonymous
        return -1;
181 2 Anonymous
}
182 2 Anonymous
</code></pre>
183 2 Anonymous
184 2 Anonymous
* Creating a new prelude client
185 2 Anonymous
186 2 Anonymous
<pre><code class="c">
187 2 Anonymous
int ret;
188 2 Anonymous
prelude_client_t *client;
189 2 Anonymous
190 2 Anonymous
ret = prelude_client_new(&client, "my-analyzer");
191 2 Anonymous
if ( ! client ) {
192 2 Anonymous
        prelude_perror(ret, "Unable to create a prelude client object");
193 2 Anonymous
		
194 2 Anonymous
		/*This suppresses the client in case it was created but still sending errors*/
195 2 Anonymous
		prelude_client_destroy(client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS);
196 2 Anonymous
        return -1;
197 2 Anonymous
}
198 2 Anonymous
</code></pre>
199 2 Anonymous
200 2 Anonymous
* Starting a new client
201 2 Anonymous
202 2 Anonymous
<pre><code class="c">
203 2 Anonymous
ret = prelude_client_start(client);
204 2 Anonymous
if ( ret < 0 ) {
205 2 Anonymous
		prelude_perror(ret, "Unable to start prelude client");
206 2 Anonymous
	   
207 2 Anonymous
	   	/*This suppresses the client in case something went wrong*/
208 2 Anonymous
		prelude_client_destroy(client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS);
209 2 Anonymous
		return -1;
210 2 Anonymous
}
211 2 Anonymous
</code></pre>
212 2 Anonymous
213 2 Anonymous
* Setting client options
214 2 Anonymous
215 2 Anonymous
<pre><code class="c">
216 2 Anonymous
ret = prelude_client_set_flags(prelude_client, PRELUDE_CLIENT_FLAGS_ASYNC_SEND|PRELUDE_CLIENT_FLAGS_ASYNC_TIMER);
217 2 Anonymous
if ( ret < 0) {
218 2 Anonymous
	fprintf(stderr, "Unable to set asynchronous send and timer.\n");
219 2 Anonymous
	
220 2 Anonymous
	/* This suppresses the client and avoid having a not configured client sending things */
221 2 Anonymous
	prelude_client_destroy(prelude_client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS); 
222 2 Anonymous
	return -1;
223 2 Anonymous
}
224 2 Anonymous
</code></pre>
225 2 Anonymous
226 2 Anonymous
* Creating the alert
227 2 Anonymous
<pre><code class="c">
228 2 Anonymous
idmef_message_t *idmef;
229 2 Anonymous
230 2 Anonymous
ret = idmef_message_new(&idmef);
231 2 Anonymous
if ( ret < 0 )
232 2 Anonymous
        return -1;
233 2 Anonymous
234 2 Anonymous
idmef_message_set_string(idmef, "alert.classification.text", "My classification text");
235 2 Anonymous
idmef_message_set_string(idmef, "alert.classification.reference(0).name", "OSVDB-XXXX");
236 2 Anonymous
idmef_message_set_string(idmef, "alert.classification.reference(0).origin", "osvdb");
237 2 Anonymous
idmef_message_set_string(idmef, "alert.classification.reference(0).url", "http://my.url/");
238 2 Anonymous
</code></pre>
239 2 Anonymous
240 2 Anonymous
* Sending the alert
241 2 Anonymous
<pre><code class="c">
242 2 Anonymous
prelude_client_send_idmef(client, idmef);
243 2 Anonymous
idmef_message_destroy(idmef);
244 2 Anonymous
</code></pre>
245 2 Anonymous
246 2 Anonymous
* Destroying the client
247 2 Anonymous
<pre><code class="c">
248 2 Anonymous
prelude_client_destroy(client, PRELUDE_CLIENT_EXIT_STATUS_SUCCESS);
249 2 Anonymous
</code></pre>
250 2 Anonymous
251 2 Anonymous
h3. Using C++