OVAL Agent
OVAL

OVAL Agent interface. More...

## 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

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. More...
struct oval_definition_model * | oval_agent_get_definition_model (oval_agent_session_t *ag_sess)
| Retrieves OVAL definition model associated with given session.
void | oval_agent_set_product_name (oval_agent_session_t *, char *)
| Set a product name for the provided agent session. More...
int | oval_agent_eval_definition (oval_agent_session_t *, const char *)
| Probe the system and evaluate specified definition. More...
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. More...
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. More...
int | oval_agent_reset_session (oval_agent_session_t *ag_sess)
| Clean resuls that were generated in this agent session.
int | oval_agent_abort_session (oval_agent_session_t *ag_sess)
| Abort a running probe session.
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. More...
struct oval_results_model * | oval_agent_get_results_model (oval_agent_session_t *ag_sess)
| Get a result model from agent session.
const char * | oval_agent_get_filename (oval_agent_session_t *ag_sess)
| Get a filename under which was created.
void | oval_agent_destroy_session (oval_agent_session_t *ag_sess)
| Finish OVAL agent session.
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. More...
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. More...
void | oval_agent_export_sysinfo_to_xccdf_result (struct oval_agent_session *session, struct xccdf_result *ritem)
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. More...

## Detailed Description

OVAL Agent interface.

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

## Typedef Documentation

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

int oval_agent_eval_definition | ( | oval_agent_session_t * | ,
|  | const char * |
| ) |  |

Probe the system and evaluate specified definition.

Returns
  0 on success; -1 error; 1 warning

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 oval_definition_model * def_model = oval_definition_model_import(oval_file);
  struct xccdf_benchmark * benchmark = xccdf_benchmark_import(file);
  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);

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

void oval_agent_export_sysinfo_to_xccdf_result | ( | struct oval_agent_session * | session,
|  | struct xccdf_result * | ritem
| ) |  |

Deprecated:
  Transform OVAL Sysinfo into XCCDF Test Result This function has been deprecated, please use xccdf_result_fill_sysinfo() instead

Parameters

  session | OVAL Agent session
  ritem | XCCDF Result

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.

Returns
  0 on success; -1 error

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

read

Get the OVAL result definition from an agent session.

Returns
  NULL if not found

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

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

void oval_agent_set_product_name | ( | oval_agent_session_t * | ,
|  | char * |
| ) |  |

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.

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