# ------------------------------------------------------------
# cawk is subjet to a MIT open-source licence
# please refer to the MIT licence file for further information
# ------------------------------------------------------------
# cawk is Copyright (C) 2024 by Cedric Llorens
# ------------------------------------------------------------

# -----------------
# ---- introduction
# -----------------

cawk objective is to provide to the community a complete list of tests allowing to check 
network configurations whatever the supplier. Moreover, cawk is ONLY based on 3 well-known
packages: 
- gnu m4 aka m4
- gnu make aka gmake
- gnu awk aka gawk

These packages are very powerful today and the cawk project intends to ONLY use these
packages. No other langage, no database, no configure, etc. cawk try to keep things simple 
and understandable for the whole. In summary, in gawk && gmake && gm4 we trust :-) 

# ----------------------
# ---- cawk installation
# ----------------------

jump to a specific directory and extract cawk, cd to cawk and type the <gmake> command in order
to have help on the cawk gmake targets. 

note : you may have to change the file support/tests.sed for finding the gawk path at your system 
level required for buidling tests:
	-%SED_GAWK_PATH% = to point out the right path for gawk 
	( we set <!/usr/bin/env -S gawk -f> for a generic finding )

# ---------------------
# ---- cawk directories
# ---------------------

cawk has the following core directories:

- checkdiff : contains a cawk compliance print to compare when running <gmake check>, to be launched only after the first installation

- common : contains a <kind of library> (set of functions) included in the tests and others common useful scripts

- m4 : contains a <kind of m4 libraries> (set of m4 functions) that may be used at exceptions or tests level

- tests : contains a collection of individual tests <*.gawk.template> or <*.gawk.m4> per supplier :

	- there are 3 types of core tests directories:
		tests/repo : contains the full collection of cawk coded tests, that can be used in tests/run or tests/run_{audit_name} directories
		tests/run  : empty by default and to be used to test or check tests (you may copy tests from tests/repo or add your own tests)
		tests/run_{audit_name} : contains the full repo tests when created (you can remove or add other tests or add your own tests)

	- inside each core tests directories, you have a full set of tests supplier directories (tests.cisco-ios, etc.)

	- a test has <.template> suffix or <.m4> suffix, but the test is converted to <.gawk> with the support of support/tests.sed and the cawk
	root Makefile. this <step> allows to write tests more easily && to enforce env system portability, so each test may to %SED_VAR% aka:

		- %SED_BLOCK_JUNIPER% : space identation used for block hierarchy
		- %SED_COMMON_PATH% = to point out the common <kind of library>
		- %SED_GAWK_PATH% = to point out the right path for gawk 
		etc.
		these values can be changed thanks to the file support/tests.sed

		moreover, a cawk m4 parse block macro allows to parse any type configuration without managing the block hierarchy level as it is
		automatically generated by the macro when the <.gawk> is generated

- confs : contains a collection of configurations per supplier

	- there are 3 types of core confs directories:
		confs/repo : contains a collection of cawk tests confs
		confs/run : empty by default and to be used to test a configuration (you may copy configurations from confs/repo or add your own configurations)
		confs/run_{audit_name} : contains the full repo confs when created (you can remove or add other configurations)

	- inside each core conf directories, you have a full set of configuration supplier directories (conf.cisco-ios, etc.)

- exceptions : contains a collection of exceptions per supplier applied for reporting

	- there are 3 types of core exceptions directories:
		exceptions/repo : contains a collection of up-and-running exceptions
		exceptions/run : contains a collection of up-and-running exceptions 
		exceptions/run_{audit_name} : contains the full repo exceptions when created

	- inside each core exception directories, you have a full set of exception supplier files (exception.cisco-ios, etc.)

- reports : contains assessment reports (and summary), each report has the same format

	- there are 3 types of core report directories:
		report/repo : empty by default, contains the repo assessment results
		report/run : empty by default, contains the run assessment results
		report/run_{audit_name} : empty by default, contains the run_{audit_name} assessment results

	- an assessment report has the following format :
		- name of the configuration
		- name of the test
		- error description
		- line number where the error has been found in the configuration
		- risklevel 
		- <pass> or <error> states

- support : contains files helping for building cawk:
	- tests.sed : used when building the tests in order to make change of the set %SED_VAR%

# -----------------------
# ---- cawk gmake targets
# -----------------------

just type <gmake> in the cawk root directory and all the cawk targets are detailed

# ------------------------
# ---- cawk gmake parallel
# ------------------------

in standard mode, cawk performs assessment not in parallel mode. to use prarallel mode,
you have to modify the Makefile.support.mk file thanks to these gmake VARS:

	# --------------- cawk parallel options
	# enable parallel yes/no
	MAKE_PARALLEL = yes
	# number of files to process per target (all targets are processed in parallel)
	MAKE_FILES_PER_TARGET = 100

	# --------------- gmake parallel options
	# gmake number of jobs
	MAKE_J = 4
	# gmake load average
	MAKE_LOAD_AVG = 3

once cawk parallel mode is enabled, before performing assessment, cawk build one Makefile
per os in tmp directory. once done, it performs each Makefile in parallel mode to offer 
enhanced performances for a huge set of files.

# --------------------
# ---- cawk risk level
# --------------------

cawk allows the following risk level:
	- high   : for (high impacts) security errors
	- medium : for (medium impacts) security errors
	- low    : for (low impacts) security errors
	- info   : for audit/information errors

# --------------------
# ---- cawk first use
# --------------------

after install, cd to the cawk root directory and type:

	- gmake : provide all cawk gmake targets

	- gmake clean check_repo view_repo : it applies the test repo to conf repo and see results, 
          you may check reports/repo assessment files 

	- gmake clean check_run view_run : it applies the test run to conf run and see results, 
          you may check reports/run assessment files 

	- gmake create_audit audit=client1 : it creates client1 assessment, all tests from repo
	  are copied, all exceptions from repo are copied, all confs from repo are copied. now, you
          may remove or/and add tests, remove and/or add true confs and run this assessment as such
          
          	- gmake check_run audit=client1 view_run : it applies the test run_client1 to conf run_client1 and 
		see results,you may also check reports/run_client1 assessment files

          	- gmake delete_audit audit=client1 : remove the client1 assessment

# -------------------
# ---- cawk community
# -------------------

if someone intends to submit a test and a configuration associated to, if approved, then the 
test will added to the package and the name of author will be added to the AUTHORS list.

enjoy in particating to cawk or to simply use cawk, 
cedric llorens.