Header file which exports the public libcorsaro API. More...

This graph shows which files directly or indirectly include this file:

Typedefs
Opaque Data Structures
typedef struct corsaro	corsaro_t
	Opaque struct holding corsaro output state.
typedef struct corsaro_in	corsaro_in_t
	Opaque struct holding corsaro input state.
typedef struct corsaro_packet	corsaro_packet_t
	Opaque struct holding corsaro packet state.
typedef struct corsaro_in_record	corsaro_in_record_t
	Opaque struct holding a corsaro record read from file.
typedef struct corsaro_header	corsaro_header_t
	Opaque struct representing a corsaro file header.
typedef struct corsaro_trailer	corsaro_trailer_t
	Opaque struct representing a corsaro file trailer.
typedef struct corsaro_interval	corsaro_interval_t
	Opaque struct representing the start or end of an interval.
typedef struct corsaro_plugin_data	corsaro_plugin_data_t
	Opaque struct representing the start of end of a plugin data block.

Functions
Corsaro output API functions
These functions are used to generate corsaro output from libtrace packets The basic process for using corsaro to generate output is: init corsaro using corsaro_alloc_output optionally call corsaro_set_interval to set the interval time optionally call corsaro_set_traceuri to set the name of the trace call corsaro_start_output to initialize the plugins (and create the files) call corsaro_per_packet with each packet to be processed call corsaro_finalize when all packets have been processed If an API function returns an error condition, it is your responsibility to call corsaro_finalize to clean up any resources corsaro is using. This is so you can decide if halting execution is really what you want to do. For example, if a packet fails to process, you may decide to log it and attempt to continue with the next packet. Beware that this could get corsaro into an unstable state if the error arose from something like malloc failing.
corsaro_t *	corsaro_alloc_output (char *template, corsaro_file_mode_t mode)
	Allocate an corsaro object.
int	corsaro_start_output (corsaro_t *corsaro)
	Initialize an corsaro object that has already been allocated.
void	corsaro_set_interval (corsaro_t *corsaro, int interval)
	Accessor function to set the interval length.
int	corsaro_set_traceuri (corsaro_t corsaro, char traceuri)
	Accessor function to set the trace uri string.
int	corsaro_enable_plugin (corsaro_t corsaro, const char plugin_name)
	Attempt to enable a plugin using the given plugin name.
const char *	corsaro_get_traceuri (corsaro_t *corsaro)
	Accessor function to get the trace uri string.
int	corsaro_set_monitorname (corsaro_t corsaro, char name)
	Accessor function to set the monitor name.
const char *	corsaro_get_monitorname (corsaro_t *corsaro)
	Accessor function to get the monitor name string.
int	corsaro_per_packet (corsaro_t corsaro, libtrace_packet_t packet)
	Perform corsaro processing on a given libtrace packet.
int	corsaro_finalize_output (corsaro_t *corsaro)
	Write the final interval and free resources allocated by corsaro.
Corsaro input API functions
These functions are used to process exising corsaro files. Similarly to using corsaro for output, the process for opening an input file is: call corsaro_alloc_input call corsaro_start_input call corsaro_in_read_record until all records have been read for each record returned, cast to the appropriate type and carry out any processing required call corsaro_in_finalize when all records have been processed
corsaro_in_t *	corsaro_alloc_input (char *corsarouri)
	Allocate an corsaro object for reading an corsaro file.
int	corsaro_start_input (corsaro_in_t *corsaro)
	Initialize an corsaro input object that has already been allocated.
corsaro_in_record_t *	corsaro_in_alloc_record (corsaro_in_t *corsaro)
	Allocate a reusable corsaro record object.
void	corsaro_in_free_record (corsaro_in_record_t *record)
	Free an corsaro record object.
off_t	corsaro_in_read_record (corsaro_in_t corsaro, corsaro_in_record_type_t record_type, corsaro_in_record_t *record)
	Read the next corsaro record from the given corsaro input file.
void *	corsaro_in_get_record_data (corsaro_in_t corsaro, corsaro_in_record_t record)
	Get a pointer data in a record.
int	corsaro_finalize_input (corsaro_in_t *corsaro)
	Close the input file and free resources allocated by corsaro.

Enumerations
enum	corsaro_in_record_type { CORSARO_IN_RECORD_TYPE_NULL = 0, CORSARO_IN_RECORD_TYPE_INTERNAL_REDIRECT = 1, CORSARO_IN_RECORD_TYPE_IO_HEADER = 2, CORSARO_IN_RECORD_TYPE_IO_TRAILER = 3, CORSARO_IN_RECORD_TYPE_IO_INTERVAL_START = 4, CORSARO_IN_RECORD_TYPE_IO_INTERVAL_END = 5, CORSARO_IN_RECORD_TYPE_IO_PLUGIN_START = 6, CORSARO_IN_RECORD_TYPE_IO_PLUGIN_END = 7, CORSARO_IN_RECORD_TYPE_DISTRIBUTIONS_START = 10, CORSARO_IN_RECORD_TYPE_DISTRIBUTIONS_END = 11, CORSARO_IN_RECORD_TYPE_DISTRIBUTIONS_ELEMENT = 12, CORSARO_IN_RECORD_TYPE_FLOWTUPLE_CLASS_START = 20, CORSARO_IN_RECORD_TYPE_FLOWTUPLE_CLASS_END = 21, CORSARO_IN_RECORD_TYPE_FLOWTUPLE_FLOWTUPLE = 22, CORSARO_IN_RECORD_TYPE_DOS_GLOBAL_HEADER = 30, CORSARO_IN_RECORD_TYPE_DOS_HEADER = 31, CORSARO_IN_RECORD_TYPE_DOS_ATTACK_VECTOR = 32 }
	Corsaro input record types. More...
enum	corsaro_file_mode { CORSARO_FILE_MODE_ASCII = 0, CORSARO_FILE_MODE_BINARY = 1, CORSARO_FILE_MODE_TRACE = 2, CORSARO_FILE_MODE_DEFAULT = CORSARO_FILE_MODE_ASCII }
	Enum of supported file modes. More...
enum	corsaro_file_compress { CORSARO_FILE_COMPRESS_NONE = WANDIO_COMPRESS_NONE, CORSARO_FILE_COMPRESS_ZLIB = WANDIO_COMPRESS_ZLIB, CORSARO_FILE_COMPRESS_BZ2 = WANDIO_COMPRESS_BZ2, CORSARO_FILE_COMPRESS_LZO = WANDIO_COMPRESS_LZO, CORSARO_FILE_COMPRESS_DEFAULT = CORSARO_FILE_COMPRESS_ZLIB }
	Supported compression types (must be kept in sync with wandio) More...
typedef enum corsaro_in_record_type	corsaro_in_record_type_t
	Corsaro input record types.
typedef enum corsaro_file_mode	corsaro_file_mode_t
	Enum of supported file modes.
typedef enum corsaro_file_compress	corsaro_file_compress_t
	Supported compression types (must be kept in sync with wandio)

Detailed Description

Header file which exports the public libcorsaro API.

Author:: Alistair King

Definition in file corsaro.h.

Typedef Documentation

typedef enum corsaro_file_compress corsaro_file_compress_t

Supported compression types (must be kept in sync with wandio)

typedef enum corsaro_file_mode corsaro_file_mode_t

Enum of supported file modes.

typedef struct corsaro_header corsaro_header_t

Opaque struct representing a corsaro file header.

Definition at line 56 of file corsaro.h.

typedef struct corsaro_in_record corsaro_in_record_t

Opaque struct holding a corsaro record read from file.

Definition at line 54 of file corsaro.h.

typedef enum corsaro_in_record_type corsaro_in_record_type_t

Corsaro input record types.

Use these types to request a specific record, or to cast a returned record, from corsaro_in_read_record

You should be able to cast this by removing the 'type' and adding '_t'. For example, CORSARO_IN_RECORD_TYPE_IO_HEADER becomes corsaro_in_record_io_header_t

Additionally, the field immediately following 'TYPE' indicates the module which is responsible for reading and writing these records. It is probably safe to look in corsaro_<module>.[ch] to find them.

typedef struct corsaro_in corsaro_in_t

Opaque struct holding corsaro input state.

Definition at line 50 of file corsaro.h.

typedef struct corsaro_interval corsaro_interval_t

Opaque struct representing the start or end of an interval.

Definition at line 60 of file corsaro.h.

typedef struct corsaro_packet corsaro_packet_t

Opaque struct holding corsaro packet state.

Definition at line 52 of file corsaro.h.

typedef struct corsaro_plugin_data corsaro_plugin_data_t

Opaque struct representing the start of end of a plugin data block.

Definition at line 62 of file corsaro.h.

typedef struct corsaro corsaro_t

Opaque struct holding corsaro output state.

Definition at line 48 of file corsaro.h.

typedef struct corsaro_trailer corsaro_trailer_t

Opaque struct representing a corsaro file trailer.

Definition at line 58 of file corsaro.h.

Enumeration Type Documentation

enum corsaro_file_compress

Supported compression types (must be kept in sync with wandio)

Enumerator:

CORSARO_FILE_COMPRESS_NONE	No compression.
CORSARO_FILE_COMPRESS_ZLIB	Zlib compression (gzip)
CORSARO_FILE_COMPRESS_BZ2	Bzip compression.
CORSARO_FILE_COMPRESS_LZO	LZO Compression.
CORSARO_FILE_COMPRESS_DEFAULT	Default compression.

Definition at line 166 of file corsaro.h.

enum corsaro_file_mode

Enum of supported file modes.

Enumerator:

CORSARO_FILE_MODE_ASCII	ASCII IO mode.
CORSARO_FILE_MODE_BINARY	Binary IO mode.
CORSARO_FILE_MODE_TRACE	Pseudo IO mode which allows trace files to be written.
CORSARO_FILE_MODE_DEFAULT	Default IO mode.

Definition at line 152 of file corsaro.h.

enum corsaro_in_record_type

Corsaro input record types.

Use these types to request a specific record, or to cast a returned record, from corsaro_in_read_record

You should be able to cast this by removing the 'type' and adding '_t'. For example, CORSARO_IN_RECORD_TYPE_IO_HEADER becomes corsaro_in_record_io_header_t

Additionally, the field immediately following 'TYPE' indicates the module which is responsible for reading and writing these records. It is probably safe to look in corsaro_<module>.[ch] to find them.

Enumerator:

CORSARO_IN_RECORD_TYPE_NULL	The null type used for wildcard matching.
CORSARO_IN_RECORD_TYPE_INTERNAL_REDIRECT	Internal type for directing read requests.
CORSARO_IN_RECORD_TYPE_IO_HEADER	The overall corsaro header (currently only in global)
CORSARO_IN_RECORD_TYPE_IO_TRAILER	The overall corsaro trailer (currently only in global)
CORSARO_IN_RECORD_TYPE_IO_INTERVAL_START	The start of an interval.
CORSARO_IN_RECORD_TYPE_IO_INTERVAL_END	The end of an interval.
CORSARO_IN_RECORD_TYPE_IO_PLUGIN_START	The start of a plugin data section.
CORSARO_IN_RECORD_TYPE_IO_PLUGIN_END	The end of a plugin data section.
CORSARO_IN_RECORD_TYPE_DISTRIBUTIONS_START	The corsaro_distributions distribution start record.
CORSARO_IN_RECORD_TYPE_DISTRIBUTIONS_END	The corsaro_distributions distribution end record.
CORSARO_IN_RECORD_TYPE_DISTRIBUTIONS_ELEMENT	The corsaro_distributions distribution element record (key/value)
CORSARO_IN_RECORD_TYPE_FLOWTUPLE_CLASS_START	The corsaro_flowtuple flowtuple classification type start record.
CORSARO_IN_RECORD_TYPE_FLOWTUPLE_CLASS_END	The corsaro_flowtuple flowtuple classification type end record.
CORSARO_IN_RECORD_TYPE_FLOWTUPLE_FLOWTUPLE	The corsaro_flowtuple flowtuple record.
CORSARO_IN_RECORD_TYPE_DOS_GLOBAL_HEADER	The corsaro_dos global header record.
CORSARO_IN_RECORD_TYPE_DOS_HEADER	The corsaro_dos header record.
CORSARO_IN_RECORD_TYPE_DOS_ATTACK_VECTOR	The corsaro_dos attack vector record.

Definition at line 84 of file corsaro.h.

Function Documentation

corsaro_in_t* corsaro_alloc_input ( char * corsarouri )

Allocate an corsaro object for reading an corsaro file.

Parameters:

corsarouri The corsaro file uri to open

Returns:: a pointer to an corsaro input structure, or NULL if an error occurs

Definition at line 915 of file corsaro.c.

corsaro_t* corsaro_alloc_output	(	char *	template,
		corsaro_file_mode_t	mode
	)

Allocate an corsaro object.

Parameters:

template	The string used to generate output files
mode	The file output mode

Returns:: a pointer to an opaque corsaro structure, or NULL if an error occurs

The template must contain a pattern to be replaced with the plugin names (P). The output modes that make sense to use are CORSARO_FILE_MODE_ASCII and CORSARO_FILE_MODE_BINARY. Using CORSARO_FILE_MODE_TRACE will result in an error as not all plugins are expected to be able to write to generic packets

The returned object can then be used to set options (corsaro_set_*) before calling corsaro_start_output to write headers to the output files ready to process packets.

Definition at line 652 of file corsaro.c.

int corsaro_enable_plugin	(	corsaro_t *	corsaro,
		const char *	plugin_name
	)

Attempt to enable a plugin using the given plugin name.

Parameters:

corsaro	The corsaro object to enable the plugin for
plugin_name	The string name of the plugin to enable

Returns:: 0 if the plugin was successfully enabled, -1 if an error occurs

Until this function is called successfully, all compiled plugins are considered enabled. Once it has been called, only the plugins explicitly enabled using this function will be used

Definition at line 751 of file corsaro.c.

References corsaro::plugin_manager, and corsaro::started.

int corsaro_finalize_input ( corsaro_in_t * corsaro )

Close the input file and free resources allocated by corsaro.

Parameters:

corsaro The corsaro input object to finalize

Returns:: 0 if corsaro finished properly, -1 if an error occurs.

Definition at line 1088 of file corsaro.c.

int corsaro_finalize_output ( corsaro_t * corsaro )

Write the final interval and free resources allocated by corsaro.

Parameters:

corsaro The corsaro object to finalize

Returns:: 0 if corsaro finished properly, -1 if an error occurs.

Definition at line 888 of file corsaro.c.

References corsaro::global_file, corsaro::last_ts, and corsaro::started.

const char* corsaro_get_monitorname ( corsaro_t * corsaro )

Accessor function to get the monitor name string.

Parameters:

corsaro The corsaro object to set the monitor name for

Returns:: a pointer to the monitor name string

Definition at line 802 of file corsaro.c.

References corsaro::monitorname, and STR.

const char* corsaro_get_traceuri ( corsaro_t * corsaro )

Accessor function to get the trace uri string.

Parameters:

corsaro The corsaro object to set the trace uri for

Returns:: a pointer to the traceuri string, or NULL if it is not set

Definition at line 768 of file corsaro.c.

References corsaro::uridata.

corsaro_in_record_t* corsaro_in_alloc_record ( corsaro_in_t * corsaro )

Allocate a reusable corsaro record object.

Parameters:

corsaro The corsaro input object to associate with the record

Returns:: a pointer to the record object, NULL if an error occurs

Definition at line 1014 of file corsaro.c.

References corsaro_in_record::buffer, corsaro_in_record::buffer_len, corsaro_in_record::corsaro, corsaro_in_free_record(), CORSARO_IN_RECORD_DEFAULT_BUFFER_LEN, and corsaro_in_record::type.

void corsaro_in_free_record ( corsaro_in_record_t * record )

Free an corsaro record object.

Parameters:

record The record object to free

Definition at line 1042 of file corsaro.c.

References corsaro_in_record::buffer, corsaro_in_record::buffer_len, and corsaro_in_record::type.

Referenced by corsaro_in_alloc_record().

void* corsaro_in_get_record_data	(	corsaro_in_t *	corsaro,
		corsaro_in_record_t *	record
	)

Get a pointer data in a record.

Parameters:

corsaro	The corsaro input object associated with the record
record	The corsaro record object to retrieve data from

Returns:: a void pointer to the data, NULL if an error occurred

Definition at line 1083 of file corsaro.c.

References corsaro_in_record::buffer.

Referenced by main().

off_t corsaro_in_read_record	(	corsaro_in_t *	corsaro,
		corsaro_in_record_type_t *	record_type,
		corsaro_in_record_t *	record
	)

Read the next corsaro record from the given corsaro input file.

Parameters:

	corsaro	The corsaro input object to read from
[in,out]		The type of the record to read
	record	The generic corsaro input record pointer

Returns:: 0 on EOF, -1 on error, number of bytes read when successful

Definition at line 1062 of file corsaro.c.

References CORSARO_IN_RECORD_TYPE_NULL, corsaro_in::expected_type, corsaro_in::plugin, and corsaro_plugin::read_record.

Referenced by main().

int corsaro_per_packet	(	corsaro_t *	corsaro,
		libtrace_packet_t *	packet
	)

Perform corsaro processing on a given libtrace packet.

Parameters:

corsaro	The corsaro object used to process the packet
packet	The libtrace packet to process

Returns:: 0 if the packet is successfully processed, -1 if an error occurs

For each packet, corsaro will determine whether it falls within the current interval, if not, it will write out data for the previous interval. The packet is then handed to each plugin which processes it and updates internal state.

Definition at line 814 of file corsaro.c.

References corsaro::first_ts, corsaro::interval, corsaro::interval_start, corsaro::last_ts, corsaro_packet::ltpacket, corsaro::next_report, corsaro_interval::number, corsaro::packet, corsaro::packet_cnt, and corsaro::started.

void corsaro_set_interval	(	corsaro_t *	corsaro,
		int	interval
	)

Accessor function to set the interval length.

Parameters:

corsaro	The corsaro object to set the interval for
interval	The interval (in seconds)

If this function is not called, the default interval, CORSARO_INTERVAL_DEFAULT, will be used.

Definition at line 714 of file corsaro.c.

References corsaro::interval, and corsaro::started.

int corsaro_set_monitorname	(	corsaro_t *	corsaro,
		char *	name
	)

Accessor function to set the monitor name.

Parameters:

corsaro	The corsaro object to set the monitor name for
name	The string to set as the monitor name

Returns:: 0 if the name was successfully set, -1 if an error occurs

If it is not set, the value defined at compile time is used. This is either the hostname of the machine it was compiled on, or a value passed to configure using –with-monitorname

Definition at line 773 of file corsaro.c.

References corsaro::monitorname, and corsaro::started.

int corsaro_set_traceuri	(	corsaro_t *	corsaro,
		char *	traceuri
	)

Accessor function to set the trace uri string.

Parameters:

corsaro	The corsaro object to set the trace uri for
traceuri	The string to set as the trace uri

Returns:: 0 if the uri was successfully set, -1 if an error occurs

The trace uri is not used internally by corsaro, this can be any user-defined string which is stored in the corsaro header in output files. If it is not set, no uri is written to the output.

Definition at line 724 of file corsaro.c.

References corsaro::started, and corsaro::uridata.

int corsaro_start_input ( corsaro_in_t * corsaro )

Initialize an corsaro input object that has already been allocated.

Parameters:

corsaro The corsaro input object to start

Returns:: 0 if corsaro is started successfully, -1 if an error occurs

Definition at line 929 of file corsaro.c.

References CORSARO_IN_RECORD_TYPE_IO_HEADER, corsaro_in::expected_type, corsaro_in::file, corsaro_plugin::init_input, corsaro_plugin::name, corsaro_in::plugin, corsaro_in::plugin_manager, corsaro_plugin::probe_filename, corsaro_plugin::probe_magic, corsaro_in::started, and corsaro_in::uridata.

int corsaro_start_output ( corsaro_t * corsaro )

Initialize an corsaro object that has already been allocated.

Parameters:

corsaro The corsaro object to start

Returns:: 0 if corsaro is started successfully, -1 if an error occurs

Definition at line 673 of file corsaro.c.

References corsaro::global_file, corsaro_plugin::init_output, corsaro::plugin_manager, and corsaro::started.

Typedefs

Functions

Enumerations

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation