Loading...
Searching...
No Matches
OVALAGENT
OVAL

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_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.
  Definition oval_agent.c:614
  oval_agent_new_session
  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.
  Definition oval_agent.c:92
  oval_definition_model::oval_definition_model_import_source
  OSCAP_API struct oval_definition_model * oval_definition_model_import_source(struct oscap_source *source)
  Import the content of the oscap_source into the oval_definition_model.
  Definition oval_defModel.c:244
  xccdf_policy_model::xccdf_policy_model_new
  OSCAP_API struct xccdf_policy_model * xccdf_policy_model_new(struct xccdf_benchmark *benchmark)
  Constructor of Policy Model structure.
  Definition xccdf_policy.c:1780
  xccdf_benchmark::xccdf_benchmark_import_source
  OSCAP_API struct xccdf_benchmark * xccdf_benchmark_import_source(struct oscap_source *source)
  Import the content from oscap_source into a benchmark.
  Definition benchmark.c:54
  oscap_source
  Definition oscap_source.c:66
  oval_agent_session
  Definition oval_agent.c:54
  oval_definition_model
  Oval definition model.
  Definition oval_defModel.c:53
  xccdf_benchmark
  Top level XCCDF structure containing profiles, rules, values and results.
  xccdf_policy_model
  XCCDF policy model structure contains xccdf_benchmark as reference to Benchmark element in XML file a...
  Definition xccdf_policy_priv.h:38
  xccdf_policy_model::benchmark
  struct xccdf_benchmark * benchmark
  Benchmark element (root element of XML file).
  Definition xccdf_policy_priv.h:40

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