diff options
Diffstat (limited to 'sechecker/modules/template')
| -rw-r--r-- | sechecker/modules/template/profiles.readme | 142 | ||||
| -rw-r--r-- | sechecker/modules/template/template.howto | 13 | ||||
| -rw-r--r-- | sechecker/modules/template/xx.c | 393 | ||||
| -rw-r--r-- | sechecker/modules/template/xx.h | 72 |
4 files changed, 620 insertions, 0 deletions
diff --git a/sechecker/modules/template/profiles.readme b/sechecker/modules/template/profiles.readme new file mode 100644 index 0000000..f781ee0 --- /dev/null +++ b/sechecker/modules/template/profiles.readme @@ -0,0 +1,142 @@ +How to write a profile for SEChecker +===================================== + +Table of Contents +======================== +1. Use of Profiles +2. Format of the Profile + 2.0 <sechecker> + 2.1 <profile> + 2.2 <module> + 2.3 <output> + 2.4 <option> +3. Example Profile + +1. Use of Profiles +========================== +SEChecker has a wide variety of modules which perform various tests +on the policy and/or system. To make the management and running of +these modules easier, several profiles are defined. + +A profile is used to run a set of modules with options set in a way +that the resulting report reflects a specific security goal. + +To write your own profile, create a new XML file named <profile name>.prof. +The format of the file is detailed below. + +2. Format of the Profile +========================= +A profile is an XML file loaded by SEChecker to run a specific set of tests. +The profile recognizes the following tags + +2.0 <sechecker> +=========================== +The sechecker tag should be the first open tag in the file and the final +tag to be closed. The tag has a single attribute version, which should +be set to the current version of SEChecker you are using. To find your +version number, run: "sechecker --version". + +<sechecker version="1.0"> + +Be sure to remember to close this tag at the end of the file. + +2.1 <profile> +=========================== +The profile tag tells the parser that SEChecker should interpret this +file as a profile. This tag has no attributes. + +<profile> + +Close this tag just before the sechecker tag is closed at the end of the file + +2.2 <module> +=========================== +The module tag tells SEChecker that a particular module should be run for +this profile. The only attribute is name. + +<module name="mod_name"> + +This tag is closed after all other tags related to that module + +2.3 <output> +========================= +The output tag tells SEChecker to use this output format for the module +in which it appears. This tag is optional and has one attribute, value. + +<output value="short"/> + +This tag should close itself. The valid values are: + none - do not print anything in the report; only run this module + as dependency of another module. + quiet - print only the stats and header in the report + short - print the header, stats, and a list of items found by the + module without any accompanying proof + long - print the header, stats, and a list of items found by the + module with proof of the result following each item + verbose - print all possible output including the header, stats, + a list of items and a list of items with proof + +NOTE: any of the above values other than "none" are overridden by the + command line output flags. Setting an output value in a profile + overrides the default setting in the configuration file for this + profile only. + +2.4 <option> +======================= +The option tag allows a profile to specify additional options for a module. +The option tag has two mandatory attributes, "name" and "value". +The values of these attributes is specific to the module for which the +option is specified. Options specified in a profile are used in addition +to those in the configuration file. + +<option name="option_name" value="some_value"/> + +This tag closes itself. As its name implies this tag is optional. + +3. Example Profile +====================== +The following is a brief example of a profile + +<sechecker version="1.0"> +<profile> + + <module name="mod1"> + </module> + + <module name="mod2"> + <output value="none"/> + <option name="attribute" value="my_attrib"/> + </module> + + <module name="mod3"> + <option name="foo" value="bar"/> + </module> + + <module name="mod4"> + <output value="short"/> + </module> + + <module name="mod5"> + <output value="quiet"/> + <option name="type" value="shadow_t"/> + </module> + +</profile> +</sechecker> + +The result of this profile would be: +- run mod1 with default configuration; + print with default settings +- run mod2 with the additional attribute my_attrib, + but don't print its results +- run mod3 with option foo set to bar (in addition to any other settings); + print with default settings +- run mod4; + print in short output +- run mod5 with additional type shadow_t; + print using quiet output + +If there are also modules mod6 and mod7, neither would be run unless +one of the other modules (mod1-5) had a dependency on them. + + diff --git a/sechecker/modules/template/template.howto b/sechecker/modules/template/template.howto new file mode 100644 index 0000000..09151e0 --- /dev/null +++ b/sechecker/modules/template/template.howto @@ -0,0 +1,13 @@ +Instructions for using the template to add new modules +======================================================== +1. copy the xx.c and xx.h files to the modules directory +2. rename the files and replace the text xx with the + module name in both files +3. add the register function for your module xx_register + to the register_list.h and register_list.c entries +4. add options and any requirements or dependencies to + the decription in the register function +5. fill out TODO sections of the template with logic for + your module +6. recompile + diff --git a/sechecker/modules/template/xx.c b/sechecker/modules/template/xx.c new file mode 100644 index 0000000..20f7f5f --- /dev/null +++ b/sechecker/modules/template/xx.c @@ -0,0 +1,393 @@ +/** + * @file + * Implementation of the xx module. + * + * @author Jeremy A. Mowery jmowery@tresys.com + * + * Copyright (C) 2005-2007 Tresys Technology, LLC + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program 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 General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/* NOTE: TODO This is a module template, which includes all the necessary + * infrastructure to implement a basic SEChecker module. To use this template + * first replace all instances of the string xx with the name of the module, + * then edit or complete all sections marked TODO as instructed. */ + +#include <config.h> + +#include "sechecker.h" +#include <apol/policy.h> +#include "xx.h" + +#include <stdio.h> +#include <string.h> +#include <errno.h> + +/* This string is the name of the module and should match the stem of the file + * name; it should also match the prefix of all functions defined in this + * module and the private data storage structure */ +static const char *const mod_name = "xx"; + +/* The register function registers all of a module's functions + * with the library. TODO: Edit the description fields to include all + * options, requirements, and dependencies. Also provide a brief summary + * of the steps performed in this module's checks. If you are adding + * additional functions you need other modules to call, see the note at + * the bottom of this function to do so. */ +int xx_register(sechk_lib_t * lib) +{ + sechk_module_t *mod = NULL; + sechk_fn_t *fn_struct = NULL; + sechk_name_value_t *nv = NULL; + + if (!lib) { + ERR(NULL, "No library"); + errno = EINVAL; + return -1; + } + + /* Modules are declared by the register list file and their name and options + * are stored in the module vector of the library. The name is looked up to + * determine where to store the function structures */ + mod = sechk_lib_get_module(mod_name, lib); + if (!mod) { + ERR(lib->policy, "Module unknown \"%s\"", mod_name); + errno = ENOENT; + return -1; + } + + mod->parent_lib = lib; + + /* TODO: assign the descriptions */ + mod->brief_description = ""; + mod->detailed_description = + "--------------------------------------------------------------------------------\n" + "TODO: detailed description for this module.\n"; + mod->opt_description = + " Module requirements:\n" " none\n" " Module dependencies:\n" " none\n" " Module options:\n" " none\n"; + mod->severity = "TODO: set proper severity"; + + /* TODO: assign default options (remove if none) + * fill name and value and repeat as needed */ + nv = sechk_name_value_new("", ""); + apol_vector_append(mod->options, (void *)nv); + + /* TODO: assign requirements (remove if none) + * fill name and value and repeat as needed */ + nv = sechk_name_value_new("", ""); + apol_vector_append(mod->requirements, (void *)nv); + + /* TODO: assign dependencies (remove if not needed) + * fill name and value and repeat as needed */ + nv = sechk_name_value_new("", ""); + apol_vector_append(mod->dependencies, (void *)nv); + + /* register functions */ + fn_struct = sechk_fn_new(); + if (!fn_struct) { + ERR(lib->policy, "%s", strerror(ENOMEM)); + errno = ENOMEM; + return -1; + } + fn_struct->name = strdup(SECHK_MOD_FN_INIT); + if (!fn_struct->name) { + ERR(lib->policy, "%s", strerror(ENOMEM)); + errno = ENOMEM; + return -1; + } + fn_struct->fn = xx_init; + apol_vector_append(mod->functions, (void *)fn_struct); + + fn_struct = sechk_fn_new(); + if (!fn_struct) { + ERR(lib->policy, "%s", strerror(ENOMEM)); + errno = ENOMEM; + return -1; + } + fn_struct->name = strdup(SECHK_MOD_FN_RUN); + if (!fn_struct->name) { + ERR(lib->policy, "%s", strerror(ENOMEM)); + errno = ENOMEM; + return -1; + } + fn_struct->fn = xx_run; + apol_vector_append(mod->functions, (void *)fn_struct); + + /* TODO: if the module does not have a private data structure + * set this function pointer to NULL */ + mod->data_free = xx_data_free; + + fn_struct = sechk_fn_new(); + if (!fn_struct) { + ERR(lib->policy, "%s", strerror(ENOMEM)); + errno = ENOMEM; + return -1; + } + fn_struct->name = strdup(SECHK_MOD_FN_PRINT); + if (!fn_struct->name) { + ERR(lib->policy, "%s", strerror(ENOMEM)); + errno = ENOMEM; + return -1; + } + fn_struct->fn = xx_print; + apol_vector_append(mod->functions, (void *)fn_struct); + + /* TODO: (optional) add any other functions needed here, + * add a block as above for each additional function */ + + return 0; +} + +/* The init function creates the module's private data storage object and + * initializes its values. Add any option processing logic as indicated below. + * TODO: add options processing logic */ +int xx_init(sechk_module_t * mod, apol_policy_t * policy, void *arg __attribute__ ((unused))) +{ + sechk_name_value_t *opt = NULL; + xx_data_t *datum = NULL; + int error = 0; + size_t i = 0; + + if (!mod || !policy) { + ERR(policy, "%s", strerror(EINVAL)); + errno = EINVAL; + return -1; + } + if (strcmp(mod_name, mod->name)) { + ERR(policy, "Wrong module (%s)\n", mod->name); + errno = EINVAL; + return -1; + } + + /* If the module doesnot have a privte data sturcture replace the following + * block with "mod->data = NULL" */ + datum = xx_data_new(); + if (!datum) { + error = errno; + ERR(policy, "Error: %s\n", strerror(error)); + errno = error; + return -1; + } + mod->data = datum; + + for (i = 0; i < apol_vector_get_size(mod->options); i++) { + opt = apol_vector_get_element(mod->options, i); + /* TODO: check options + * check strings opt->name and opt->value of each option + * to set the members of the private data storage object + * (pointed to by datum). + * i.e. if (!strcmp(...)) {} else if (!strcmp((...)) etc. + * There should be relatively few options for any one module. + * If too many options are needed consider splitting the check + * into multiple modules and using dependencies. It is desirable + * for all checks to be a simple and granular as is possible */ + } + + return 0; +} + +/* The run function performs the check. This function runs only once + * even if called multiple times. All test logic should be placed below + * as instructed. This function allocates the result structure and fills + * in all relavant item and proof data. + * Return Values: + * -1 System error + * 0 The module "succeeded" - no negative results found + * 1 The module "failed" - some negative results found + * TODO: add check logic */ +int xx_run(sechk_module_t * mod, apol_policy_t * policy, void *arg __attribute__ ((unused))) +{ + xx_data_t *datum; + sechk_result_t *res = NULL; + sechk_item_t *item = NULL; + sechk_proof_t *proof = NULL; + int error = 0; + + /* TODO: define any aditional variables needed */ + + if (!mod || !policy) { + ERR(policy, "%s", strerror(EINVAL)); + errno = EINVAL; + return -1; + } + if (strcmp(mod_name, mod->name)) { + ERR(policy, "Wrong module (%s)", mod->name); + return -1; + } + + /* if already run return */ + if (mod->result) + return 0; + + datum = (xx_data_t *) mod->data; + res = sechk_result_new(); + if (!res) { + error = errno; + ERR(policy, "%s", strerror(error)); + errno = error; + return -1; + } + res->test_name = strdup(mod_name); + if (!res->test_name) { + error = errno; + ERR(policy, "%s", strerror(error)); + goto xx_run_fail; + } + /* TODO: set res->item_type to indicate which array the item_id indexes + * use values from the sechk_item_type_e enum (see sechecker.h) */ + + /* TODO: check logic here + * Perform check here. Create and initialize items and proof as found, + * appending to the appropriate vectors. + * For examples of the type of code to use here see other modules. */ + + mod->result = res; + + /* If module finds something that would be considered a failure + * of the policy return 1 here */ + if (apol_vector_get_size(res->items) > 0) + return 1; + + return 0; + + xx_run_fail: + /* TODO: free any other memory allocated during check logic */ + sechk_proof_free(proof); + sechk_item_free(item); + sechk_result_destroy(&res); + errno = error; + return -1; +} + +/* The free function frees the private data of a module + * TODO: be sure to free any allocated space in the private data */ +void xx_data_free(void *data) +{ + xx_data_t *datum = (xx_data_t *) data; + + if (datum) { + /* TODO: free any allocated members of the module's + * private data structure */ + } + + free(data); +} + +/* The print function generates the text and prints the results to stdout. The + * outline below prints the standard format of a report section. Some modules + * may not have results in a format that can be represented by this outline and + * will need a different specification. It is required that each of the flags + * for output components be tested in this function (stats, list, proof, + * detailed, and brief) TODO: fill in the indicated information in the report + * fields as indicated below. Some alteration may be necessary for checks that + * perform different analyses */ +int xx_print(sechk_module_t * mod, apol_policy_t * policy, void *arg __attribute__ ((unused))) +{ + xx_data_t *datum = NULL; + unsigned char outformat = 0x00; + sechk_item_t *item = NULL; + sechk_proof_t *proof = NULL; + size_t i = 0, j = 0; + + if (!mod || !policy) { + ERR(policy, "%s", strerror(EINVAL)); + errno = EINVAL; + return -1; + } + if (strcmp(mod_name, mod->name)) { + ERR(policy, "Wrong module (%s)", mod->name); + errno = EINVAL; + return -1; + } + + datum = (xx_data_t *) mod->data; + outformat = mod->outputformat; + + if (!mod->result) { + ERR(policy, "Module %s has not been run", mod->name); + errno = EINVAL; + return -1; + } + + if (!outformat || (outformat & SECHK_OUT_QUIET)) + return 0; /* not an error - no output is requested */ + + /* TODO: display the statistics of the results + * typical text is "Found %i <itemtype>.\n" + * additional information may be printed here depending upon + * the amount of data gathered in the check */ + if (outformat & SECHK_OUT_STATS) { + /* TODO: "Found %i <itemtype>.\n": enter itemtype */ + printf("Found %zd .\n", apol_vector_get_size(mod->result->items)); + /* TODO: any additional generated statistics */ + } + /* The list report component is a display of all items found without any + * supporting proof. The default method is to display a comma separated list + * four items to a line this may need to be changed for longer items. + * TODO: you will need to enter the string representation of + * each item as the second parameter in the printf statement + * in place of the empty string. + * NOTE: if the item is a type of rule print only one per line. */ + if (outformat & SECHK_OUT_LIST) { + printf("\n"); + for (i = 0; i < apol_vector_get_size(mod->result->items); i++) { + item = apol_vector_get_element(mod->result->items, i); + i++; + /* TODO: (optional) change the number below to + * print more or less than 4 items per line */ + i %= 4; + /* TODO: second parameter: item name */ + printf("%s%s", "", (i ? ", " : "\n")); + } + printf("\n"); + } + /* The proof report component is a display of a list of items with an + * indented list of proof statements supporting the result of the check for + * that item (e.g. rules with a given type). Each proof element is then + * displayed in an indented list one per line below it. + * TODO: the name of the item should be entered below. + * NOTE: certain checks may need to further modify this report component if + * the results cannot be presented in this format */ + if (outformat & SECHK_OUT_PROOF) { + printf("\n"); + for (i = 0; i < apol_vector_get_size(mod->result->items); i++) { + item = apol_vector_get_element(mod->result->items, i); + printf("%s", ""); /* TODO: item name */ + printf(" - severity: %s\n", sechk_item_sev(item)); + for (j = 0; j < apol_vector_get_size(item->proof); j++) { + proof = apol_vector_get_element(item->proof, j); + printf("\t%s\n", proof->text); + } + } + printf("\n"); + } + + return 0; +} + +/* The xx_data_new function allocates and returns an initialized private data + * storage structure for this module. + * TODO: initialize any non-zero/non-null data (if needed) below */ +xx_data_t *xx_data_new(void) +{ + xx_data_t *datum = NULL; + + datum = (xx_data_t *) calloc(1, sizeof(xx_data_t)); + + /* TODO: initialize data */ + + return datum; +} diff --git a/sechecker/modules/template/xx.h b/sechecker/modules/template/xx.h new file mode 100644 index 0000000..d8c18b8 --- /dev/null +++ b/sechecker/modules/template/xx.h @@ -0,0 +1,72 @@ +/** + * @file + * Defines the interface for the xx module. + * + * @author Jeremy A. Mowery jmowery@tresys.com + * + * Copyright (C) 2005-2007 Tresys Technology, LLC + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program 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 General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + */ + +/* NOTE: TODO This is a module template, which includes all the necessary + * infrastructure to implement a basic SEChecker module. To use this template + * first replace all instances of the string xx with the name of the module, + * then edit or complete all sections marked TODO as instructed. Do not forget + * to add an entry in the register_list files (see these files for further + * instruction) */ + +#include "sechecker.h" +#include <apol/policy.h> + +/* The xx_data structure is used to hold the check specific + * private data of a module. + * TODO: Add any members you need to perform the check or if the module is not + * going to need private data remove this declaration and the data_new() and + * data_free() functions */ +typedef struct xx_data +{ + /* TODO: define members of this data structure + * for module's private data */ +} xx_data_t; + +/* The following functions are used to allocate and initialize the private data + * storage structure for this module and to free all memory used by it. */ +xx_data_t *xx_data_new(void); +void xx_data_free(void *data); + +/* The register function places the needed information about the module in the + * library, including description fields and the functions available. TODO: be + * sure to add an entry for this function in the register_list files. */ +int xx_register(sechk_lib_t * lib); + +/* Module functions: + * The following three functions (init, run, and print) must exist for all + * modules. NOTE: while using a modular format SEChecker is built statically; + * this means that all modules and their functions are in the same namespace. + * Be sure to choose a unique name for each module and to set the module name + * prefix xx everywhere */ +int xx_init(sechk_module_t * mod, apol_policy_t * policy, void *arg); +int xx_run(sechk_module_t * mod, apol_policy_t * policy, void *arg); +int xx_print(sechk_module_t * mod, apol_policy_t * policy, void *arg); + +/* TODO: (optional) Declare any other functions needed by other modules here. + * The prototype of the function must be int xx_fn(sechk_module_t *mod, + * apol_policy_t *policy, void *arg). For use by the get_module_function() + * function, be sure to add a block in the xx_register function to register + * your function. + * NOTE: While SEChecker is build statically, it is intended that no module + * directly call a function from another but instead use get_module_function() + * to get the desired function from the library. */ |