OVALAGENT

OVAL Agent interface More...

Collaboration diagram for OVALAGENT:

Files
file	oval_agent_api.h
file	oval_agent_xccdf_api.h

Typedefs
typedef struct oval_agent_session	oval_agent_session_t
	Agent session consists of connection to system checking engine, definition model, system characteristics model and results model.
typedef int(*	agent_reporter) (const struct oval_result_definition *res_def, void *arg)
typedef xccdf_test_result_type_t	xccdf_policy_eval_rule_cb_t(struct xccdf_policy *policy, const char *rule_id, const char *id, struct xccdf_value_binding_iterator *it, void *usr)

Functions
OSCAP_API oval_agent_session_t *	oval_agent_new_session (struct oval_definition_model *model, const char *name)
	Create new session for OVAL agent from OVAL definition model.
OSCAP_API struct oval_definition_model *	oval_agent_get_definition_model (oval_agent_session_t *ag_sess)
	Retrieves OVAL definition model associated with given session.
OSCAP_API void	oval_agent_set_product_name (oval_agent_session_t *, char *)
	Set a product name for the provided agent session.
OSCAP_API int	oval_agent_eval_definition (oval_agent_session_t *, const char *)
	Probe the system and evaluate specified definition.
OSCAP_API int	oval_agent_get_definition_result (oval_agent_session_t *, const char *, oval_result_t *)
	Get the OVAL result of a definition from an agent session.
OSCAP_API struct oval_result_definition *	oval_agent_get_result_definition (oval_agent_session_t *ag_sess, const char *id)
	Get the OVAL result definition from an agent session.
OSCAP_API int	oval_agent_reset_session (oval_agent_session_t *ag_sess)
	Clean resuls that were generated in this agent session.
OSCAP_API void	oval_agent_reset_syschar (oval_agent_session_t *ag_sess)
	Clean system characteristics that were generated in this agent session.
OSCAP_API void	oval_agent_reset_results (oval_agent_session_t *ag_sess)
	Clean results that were generated in this agent session.
OSCAP_API int	oval_agent_abort_session (oval_agent_session_t *ag_sess)
	Abort a running probe session.
OSCAP_API int	oval_agent_eval_system (oval_agent_session_t *ag_sess, agent_reporter cb, void *arg)
	Probe and evaluate all definitions from the content, call the callback functions upon single evaluation.
OSCAP_API struct oval_results_model *	oval_agent_get_results_model (oval_agent_session_t *ag_sess)
	Get a result model from agent session.
OSCAP_API const char *	oval_agent_get_filename (oval_agent_session_t *ag_sess)
	Get a filename under which was created.
OSCAP_API void	oval_agent_destroy_session (oval_agent_session_t *ag_sess)
	Finish OVAL agent session.
OSCAP_API xccdf_test_result_type_t	oval_agent_eval_rule (struct xccdf_policy *policy, const char *rule_id, const char *id, const char *href, struct xccdf_value_binding_iterator *it, struct xccdf_check_import_iterator *check_import_it, void *usr)
	Internal OVAL Agent Callback that can be used to evaluate XCCDF content.
OSCAP_API int	oval_agent_resolve_variables (struct oval_agent_session *session, struct xccdf_value_binding_iterator *it)
	Resolve variables from XCCDF Value Bindings and set their values to OVAL Variables.
OSCAP_API bool	xccdf_policy_model::xccdf_policy_model_register_engine_oval (struct xccdf_policy_model *model, struct oval_agent_session *sess)
	Function to register predefined oval callback for XCCDF evaluation proccess.

Detailed Description

OVAL Agent interface

OVAL Agent interface

This is a high level API for system probing and OVAL Definition content evaluation.

Typedef Documentation

xccdf_policy_eval_rule_cb_t

typedef xccdf_test_result_type_t xccdf_policy_eval_rule_cb_t(struct xccdf_policy *policy, const char *rule_id, const char *id, struct xccdf_value_binding_iterator *it, void *usr)

Parameters

policy	XCCDF Policy that is being evaluated
rule_id	ID of XCCDF Rule
id	ID of OVAL definition
it	XCCDF Value Binding iterator with value bindings
usr	Void pointer to the user data structure

Returns

XCCDF test result type of evaluated rule

Function Documentation

oval_agent_eval_definition()

OSCAP_API int oval_agent_eval_definition	(	oval_agent_session_t *	ag_sess,
		const char *	id )

Probe the system and evaluate specified definition.

Returns

0 on success; -1 error; 1 warning

oval_agent_eval_rule()

OSCAP_API xccdf_test_result_type_t oval_agent_eval_rule	(	struct xccdf_policy *	policy,
		const char *	rule_id,
		const char *	id,
		const char *	href,
		struct xccdf_value_binding_iterator *	it,
		struct xccdf_check_import_iterator *	check_import_it,
		void *	usr )

Internal OVAL Agent Callback that can be used to evaluate XCCDF content.

You can either register this function with xccdf_policy (old fashioned way as described in the example bellow). Alternativelly you can use high level function xccdf_policy_model_register_engine_oval() (recommended) which will register the oval_engine.

Example

Next example shows common use of this function in evaluation proccess of XCCDF file.

struct oscap_source *source = oscap_source_new_from_file(file);
struct oval_definition_model *def_model = oval_definition_model_import_source(source);
struct xccdf_benchmark *benchmark = xccdf_benchmark_import_source(source);
struct xccdf_policy_model *policy_model = xccdf_policy_model_new(benchmark);
struct oval_agent_session *sess = oval_agent_new_session(def_model, "name-of-file");
...
xccdf_policy_model_register_engine_and_query_callback(policy_model, "http://oval.mitre.org/XMLSchema/oval-definitions-5", oval_agent_eval_rule, (void *) sess, NULL);

oval_agent_eval_system()

OSCAP_API int oval_agent_eval_system	(	oval_agent_session_t *	ag_sess,
		agent_reporter	cb,
		void *	arg )

Probe and evaluate all definitions from the content, call the callback functions upon single evaluation.

Returns

0 on success; -1 error; 1 warning

oval_agent_get_definition_result()

OSCAP_API int oval_agent_get_definition_result	(	oval_agent_session_t *	ag_sess,
		const char *	id,
		oval_result_t *	result )

Get the OVAL result of a definition from an agent session.

Returns

0 on success; -1 error

oval_agent_get_result_definition()

OSCAP_API struct oval_result_definition * oval_agent_get_result_definition	(	oval_agent_session_t *	ag_sess,
		const char *	id )

Get the OVAL result definition from an agent session.

Returns

NULL if not found

oval_agent_new_session()

OSCAP_API oval_agent_session_t * oval_agent_new_session	(	struct oval_definition_model *	model,
		const char *	name )

Create new session for OVAL agent from OVAL definition model.

Parameters

model	OVAL Definition model
name	Name of file that can be referenced from XCCDF Benchmark

oval_agent_resolve_variables()

OSCAP_API int oval_agent_resolve_variables	(	struct oval_agent_session *	session,
		struct xccdf_value_binding_iterator *	it )

Resolve variables from XCCDF Value Bindings and set their values to OVAL Variables.

Parameters

session	OVAL Agent Session
it	XCCDF Value Bindng iterator

Returns

0 if resolving pass

Example

Example in oval_agent.c in function oval_agent_eval_rule

oval_agent_set_product_name()

OSCAP_API void oval_agent_set_product_name	(	oval_agent_session_t *	ag_sess,
		char *	product_name )

Set a product name for the provided agent session.

The product name should be used for all newly created OVAL documents. If there already are some models in the session, they are modified as well.

xccdf_policy_model_register_engine_oval()

OSCAP_API bool xccdf_policy_model_register_engine_oval	(	struct xccdf_policy_model *	model,
		struct oval_agent_session *	sess )

Function to register predefined oval callback for XCCDF evaluation proccess.

Parameters

model	XCCDF Policy Model
sess	oval_agent_session_t parameter for passing session data to callback

Returns

true if callback registered succesfully, false otherwise