# ------------------------------------------------------------
# cawk is subjet to a MIT open-source licence
# please refer to the MIT licence file for further information
# ------------------------------------------------------------
# cawk is Copyright (C) 2024-2025 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  : a full copy of repo by default (you may copy tests from tests/repo 
		or add your own tests)
		- tests/run_{audit_name} : contains a full copy of 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

	- 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 : a full copy of repo by default (you may copy configurations from confs/repo 
		or add your own configurations)
		- confs/run_{audit_name} : a full copy of 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

- 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 (a full copy of repo)
		- exceptions/run_{audit_name} : contains a full copy of repo exceptions when created

	- inside each core exception directories, you have a full set of exception supplier files

- 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 view_run audit=client1 : it applies the test run_client1 
		to conf run_client1 and see results,you may also check reports/run_client1 
		assessment files

          	- gmake check_run view_run audit=client1 supplier=cisco-ios : same as previous
		but only for cisco-ios configurations 

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

the requester must use a Pull Request to submit an evolution as such:

	# project clone
	git clone https://github.com/cedricllorens/cawk.git
	cd cawk

	# build your own develop branch
	git checkout -b cawk_name_update

	# perform your changes
	git add .
	git commit -m "Update ..."

	# push your update
	git push origin cawk_name_update

	# create the push request at Github

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