From 47be9ff57e72906660bb62a515222f482131e1fb Mon Sep 17 00:00:00 2001 From: Miroslav Grepl Date: Fri, 11 Apr 2014 09:37:53 +0200 Subject: Create setools-3.3.7 git repo --- libseaudit/include/seaudit/model.h | 362 +++++++++++++++++++++++++++++++++++++ 1 file changed, 362 insertions(+) create mode 100644 libseaudit/include/seaudit/model.h (limited to 'libseaudit/include/seaudit/model.h') diff --git a/libseaudit/include/seaudit/model.h b/libseaudit/include/seaudit/model.h new file mode 100644 index 0000000..e5daacf --- /dev/null +++ b/libseaudit/include/seaudit/model.h @@ -0,0 +1,362 @@ +/** + * @file + * + * Public interface to a seaudit_model. This represents a subset of + * log messages from one or more seaudit_log, where the subset is + * defined by a finite set of seaudit_filter and sorted by some + * criterion or criteria. + * + * @author Jeremy A. Mowery jmowery@tresys.com + * @author Jason Tang jtang@tresys.com + * + * Copyright (C) 2004-2007 Tresys Technology, LLC + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef SEAUDIT_MODEL_H +#define SEAUDIT_MODEL_H + +#ifdef __cplusplus +extern "C" +{ +#endif + +#include "filter.h" +#include "log.h" +#include "message.h" +#include "sort.h" + +#include + + typedef struct seaudit_model seaudit_model_t; + +/** + * Create a seaudit_model based upon the messages from some particular + * seaudit_log. The model will be initialized with the default filter + * (i.e., accept all of the messages from the log). + * + * @param name Name for the model; the string will be duplicated. If + * NULL then the model will be assigned a non-unique default name. + * @param log Initial log for this model to watch. If NULL then do + * not watch any log files. + * + * @return An initialized model, or NULL upon error. The caller must + * call seaudit_model_destroy() afterwards. + */ + extern seaudit_model_t *seaudit_model_create(const char *name, seaudit_log_t * log); + +/** + * Create a new seaudit_model object, initialized with the data from + * an existing model. This will do a deep copy of the original model. + * The new model will be watch the same logs that the original model + * was watching. + * + * @param model Model to clone. + * + * @return A cloned model, or NULL upon error. The caller must call + * seaudit_model_destroy() afterwards. + */ + extern seaudit_model_t *seaudit_model_create_from_model(const seaudit_model_t * model); + +/** + * Create and return a model initialized from the contents of a XML + * configuration file. This will also load filters into the model. + * The model will not be associated with any logs; for that call + * seaudit_model_append_log(). + * + * @param filename File containing model data. + * + * @return An initialized model, or NULL upon error. The caller must + * call seaudit_model_destroy() afterwards. + * + * @see seaudit_model_save_to_file() + */ + extern seaudit_model_t *seaudit_model_create_from_file(const char *filename); + +/** + * Destroy the referenced seadit_model object. + * + * @param model Model to destroy. The pointer will be set to NULL + * afterwards. (If pointer is already NULL then do nothing.) + */ + extern void seaudit_model_destroy(seaudit_model_t ** model); + +/** + * Save to disk, in XML format, the given model's values. This + * includes the filters contained within the model as well. Note that + * this does not save the messages within the model nor the associated + * logs. + * + * @param model Model to save. + * @param filename Name of the file to write. If the file already + * exists it will be overwritten. + * + * @return 0 on success, < 0 on error. + * + * @see seaudit_model_create_from_file() + */ + extern int seaudit_model_save_to_file(const seaudit_model_t * model, const char *filename); + +/** + * Get the name of this model. + * + * @param model Model whose name to get. + * + * @return Name of the model, or NULL upon error. Do not modify this + * string. + */ + extern const char *seaudit_model_get_name(const seaudit_model_t * model); + +/** + * Set the name of this model, overwriting any previous name. + * + * @param model Model whose name to set. + * @param name New name for the model; the string will be duplicated. + * If NULL then the model will be assigned a non-unique default name. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_set_name(seaudit_model_t * model, const char *name); + +/** + * Have the given model start watching the given log file, in addition + * to any other log files the model was watching. + * + * @param model Model to modify. + * @param log Additional log file to watch. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_append_log(seaudit_model_t * model, seaudit_log_t * log); + +/** + * Append a filter to a model. The next time the model's messages are + * retrieved only those messages that match this filter will be + * returned. Multiple filters may be applied to a model. Upon + * success, the model takes ownership of the filter. + * + * @param model Model to modify. + * @param filter Additional filter to be applied. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_append_filter(seaudit_model_t * model, seaudit_filter_t * filter); + +/** + * Get the list of filters for a model. Whenever a filter is modified + * the model will be recomputed. Note: to remove a filter from the + * model use seaudit_model_remove_filter(). + * + * @param model Model containing filters. + * + * @return Vector of seaudit_filter objects, or NULL upon error. Note + * that the vector my be empty. Do not destroy or otherwise modify + * this vector. (It is safe to manipulate the elements within the + * vector.) + */ + extern const apol_vector_t *seaudit_model_get_filters(const seaudit_model_t * model); + +/** + * Remove a filter from a model. The given parameter must match one + * of the filters stored within the model; call + * seaudit_model_get_filters() to get a list of the model's filters. + * + * @param model Model to modify. + * @param filter Filter to remove. Upon success the pointer becomes + * invalid. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_remove_filter(seaudit_model_t * model, seaudit_filter_t * filter); + +/** + * Set a model to accept a message if all filters are met (default + * behavior) or if any filter is met. Note that is independent from + * the setting given to seaudit_model_set_filter_visible(). + * + * @param model Model to modify. + * @param match Matching behavior if model has multiple filters. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_set_filter_match(seaudit_model_t * model, seaudit_filter_match_e match); + +/** + * Get the current filter match value for a model. + * + * @param model Model containing filter match value. + * + * @return One of SEAUDIT_FILTER_MATCH_ALL or SEAUDIT_FILTER_MATCH_ANY. + */ + extern seaudit_filter_match_e seaudit_model_get_filter_match(const seaudit_model_t * model); + +/** + * Set a model to either show (default behavior) or hide messages + * accepted by the filters. Note that is independent from the setting + * given to seaudit_model_set_filter_match(). + * + * @param model Model to modify. + * @param visible Messages to show if model has any filters. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_set_filter_visible(seaudit_model_t * model, seaudit_filter_visible_e visible); + +/** + * Get the current filter visibility value for a model. + * + * @param model Model containing filter visibility value. + * + * @return One of SEAUDIT_FILTER_VISIBLE_SHOW or + * SEAUDIT_FILTER_VISIBLE_HIDE. + */ + extern seaudit_filter_visible_e seaudit_model_get_filter_visible(const seaudit_model_t * model); + +/** + * Append a sort criterion to a model. The next time the model's + * messages are retrieved they will be sorted by this criterion. If + * the model already has sort criteria, they will have a higher + * priority than this new criterion. Upon success, the model takes + * ownership of the sort object + * + * @param model Model to modify. + * @param sort Additional sort criterion. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_append_sort(seaudit_model_t * model, seaudit_sort_t * sort); + +/** + * Remove all sort criteria from this model. The next time the + * model's messages are retrieved they will be in the same order as + * provided by the model's log(s). + * + * @param model Model to modify. + * + * @return 0 on success, < 0 on error. + */ + extern int seaudit_model_clear_sorts(seaudit_model_t * model); + +/** + * Return a value indicating if this model has changed since the last + * time seaudit_model_get_messages() was called. Note that upon a + * non-zero return value, the vector returned by + * seaudit_model_get_messages() might contain the same messages. For + * example, the user could have removed all sorts but then re-inserted + * them in the same order. + * + * @param model Model to check. + * + * @return 0 if the model is unchanged, non-zero if it may have + * changed. + */ + extern int seaudit_model_is_changed(const seaudit_model_t * model); + +/** + * Return a sorted list of messages associated with this model. This + * will cause the model to recalculate, as necessary, all messages + * according to its filters and then sort them. + * + * @param log Log to which report error messages. + * @param model Model containing messages. + * + * @return A newly allocated vector of seaudit_message_t, pre-filtered + * and pre-sorted, or NULL upon error. The caller is responsible for + * calling apol_vector_destroy() upon this value. + */ + extern apol_vector_t *seaudit_model_get_messages(const seaudit_log_t * log, seaudit_model_t * model); + +/** + * Return a sorted list of malformed messages associated with this + * model. This is the union of all malformed messages from the + * model's logs. This will cause the model to recalculate, as + * necessary, all messages according to its filters. + * + * @param log Log to which report error messages. + * @param model Model containing malformed messages. + * + * @return A newly allocated vector of strings, or NULL upon error. + * Treat the contents of the vector as const char *. The caller is + * responsible for calling apol_vector_destroy() upon this value. + */ + extern apol_vector_t *seaudit_model_get_malformed_messages(const seaudit_log_t * log, seaudit_model_t * model); + +/** + * Hide a message from a model such that the next time + * seaudit_model_get_messages() is called, the given message will not + * be returned within the vector. + * + * @param model Model containing message to hide. + * @param message Message to be marked hidden. If NULL, then do + * nothing. It is safe to make duplicate calls to this function with + * the same message. + */ + extern void seaudit_model_hide_message(seaudit_model_t * model, const seaudit_message_t * message); + +/** + * Return the number of avc allow messages currently within the model. + * This will cause the model to recalculate, as necessary, all + * messages according to its filters. + * + * @param log Log to which report error messages. + * @param model Model to get statistics. + * + * @return Number of allow messages in the model. This could be zero. + */ + extern size_t seaudit_model_get_num_allows(const seaudit_log_t * log, seaudit_model_t * model); + +/** + * Return the number of avc deny messages currently within the model. + * This will cause the model to recalculate, as necessary, all + * messages according to its filters. + * + * @param log Log to which report error messages. + * @param model Model to get statistics. + * + * @return Number of deny messages in the model. This could be zero. + */ + extern size_t seaudit_model_get_num_denies(const seaudit_log_t * log, seaudit_model_t * model); + +/** + * Return the number of boolean change messages currently within the + * model. This will cause the model to recalculate, as necessary, all + * messages according to its filters. + * + * @param log Log to which report error messages. + * @param model Model to get statistics. + * + * @return Number of boolean messages in the model. This could be + * zero. + */ + extern size_t seaudit_model_get_num_bools(const seaudit_log_t * log, seaudit_model_t * model); + +/** + * Return the number of load messages currently within the model. + * This will cause the model to recalculate, as necessary, all + * messages according to its filters. + * + * @param log Log to which report error messages. + * @param model Model to get statistics. + * + * @return Number of load messages in the model. This could be zero. + */ + extern size_t seaudit_model_get_num_loads(const seaudit_log_t * log, seaudit_model_t * model); + +#ifdef __cplusplus +} +#endif + +#endif -- cgit