# ------------------------------------------------------------
# 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 two packages are very powerful today and the cawk project intend to ONLY use these two 
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 we trust :-) (perhaps because 
i was using awk in the 1986 years !!).

cawk project allows the community to easily add their own test and their configuration associated 
to. cawk enforces a high level of granularity to allow everyone to build a test.

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

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 directories:

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

- m4   : contain a collection of m4 libraries defining m4 functions that may be used at exceptions or tests level

- tests   : a collection of individual tests *.template per supplier :

	- each supplier test (cisco-ios, etc) is divided into two part:
		- repo : this is the cawk collection of tests 
		(gmake tests_repo && check_repo to launch)
		- run  : used to put tests (from repo) that apply to your environment 
		(gmake tests_run && check_run to launch)

	- a tests has <.template> suffix or <.m4> suffix, but the test is converted to <.gawk> suffix thanks to
	the file support/tests.sed for <.template suffix> and thanks to the file support/tests.sed and m4 preprocessing. 
        this change allows to write tests more easily && enforce env system portability, so each test refer 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

- confs   : a collection of configurations per supplier

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

- report  : assessment reports (and summary), each report has a same 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
# -----------------------

cawk in gmake targets:
	- gmake			: provide information on cawk running
	- gmake system		: check if the system can run cawk
	- gmake supplier	: provides the suppliers supported by cawk
	- gmake common          : provide the list of functions available in the common directory
	- gmake clean 		: clean all 
	- gmake tests_run 	: build all <repo> tests
	- gmake tests_repo 	: build all <repo> tests
	- gmake check_repo 	: assess the confs with <repo> tests
	  or gmake clean check_repo supplier=cisco-ios (or juniper-junos, etc.)
	- gmake check_run 	: assess the confs with <run> tests
	  or gmake clean check_run supplier=cisco-ios (or juniper-junos, etc.)
	- gmake view		: view assessment reports (and summary)
	  or gmake clean check_repo view supplier=cisco-ios (or juniper-junos, etc.)
	  or gmake clean check_run view supplier=cisco-ios (or juniper-junos, etc.)
	- gmake view_error	: view assessment reports errors
	  or gmake clean check_repo view_error supplier=cisco-ios (or juniper-junos, etc.)
	  or gmake clean check_run view_error supplier=cisco-ios (or juniper-junos, etc.)
	- gmake catalog 	: list the tests linked to <repo> or <run>

	note : gmake clean check_repo view allows to launch a full <repo> assessment

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