diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ce2f01a3..723f79b6 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -48,7 +48,7 @@ jobs: - name: install dependencies run: | sudo apt-get update -q - sudo apt-get install -y uthash-dev libconfuse-dev autoconf-archive bison byacc flex valgrind help2man bats + sudo apt-get install -y uthash-dev libconfuse-dev autoconf-archive bison byacc flex valgrind asciidoctor bats # Install libcheck from source. Ubuntu is on version 0.10.0, and ck_assert_ptr_null and # ck_assert_ptr_nonnull were added in 0.11.0 - name: checkout check diff --git a/configure.ac b/configure.ac index 0a66b1f2..160118b5 100644 --- a/configure.ac +++ b/configure.ac @@ -66,13 +66,13 @@ AC_ARG_ENABLE([gcov], AM_CONDITIONAL([COND_GCOV],[ test "x$enable_gcov" "=" "xyes" ]) -AC_CHECK_PROGS([HELP2MAN], [help2man]) -if ! test -z "$HELP2MAN" +AC_CHECK_PROGS([ASCIIDOCTOR], [asciidoctor]) +if ! test -z "$ASCIIDOCTOR" then AC_SUBST(MANPAGES, selint.1) -HAVE_HELP2MAN=true +HAVE_ASCIIDOCTOR=true fi -AM_CONDITIONAL([HAVE_HELP2MAN], [test "x$HAVE_HELP2MAN" "=" "xtrue"]) +AM_CONDITIONAL([HAVE_ASCIIDOCTOR], [test "x$HAVE_ASCIIDOCTOR" "=" "xtrue"]) AX_VALGRIND_DFLT([drd], [off]) AX_VALGRIND_DFLT([helgrind], [off]) diff --git a/man/Makefile.am b/man/Makefile.am index b82ecd0b..f22f124b 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -12,15 +12,15 @@ # See the License for the specific language governing permissions and # limitations under the License. -SOURCES=selint.h2m +SOURCES=selint.adoc -if HAVE_HELP2MAN +if HAVE_ASCIIDOCTOR man1_MANS=$(MANPAGES) EXTRA_DIST=$(man1_MANS) $(SOURCES) CLEANFILES=$(MANPAGES) -selint.1: ../src/main.c $(SOURCES) - $(HELP2MAN) -n "Perform static source code analysis on SELinux policy source files" -N -i selint.h2m -o $@ ../src/selint +selint.1: $(SOURCES) + $(ASCIIDOCTOR) --failure-level INFO --warnings --verbose --backend manpage $^ --out-file $@ else EXTRA_DIST=$(SOURCES) endif diff --git a/man/selint.adoc b/man/selint.adoc new file mode 100644 index 00000000..c547d665 --- /dev/null +++ b/man/selint.adoc @@ -0,0 +1,298 @@ += selint(1) +:doctype: manpage +:release-version: 1.4.0 +:manmanual: SELint Manual +:mansource: SELint {release-version} + +== Name + +SELint - Perform static source code analysis on SELinux policy source files + + +== Synopsis + +*selint* [_OPTION_]... _FILE_... + + +== Options + +*-c, --config*=_CONFIGFILE_:: + Override default config with config specified on command line. + See CONFIGURATION section for config file syntax. + +*--color*=_COLOR_OPTION_:: + Configure color output. + Options are _on_, _off_ and _auto_ (the default). + +*--context*=_CONTEXT_PATH_:: + Recursively scan CONTEXT_PATH to find additional te and if files to parse, but not scan. + SELint will assume the scanned policy files are intended to be compiled together with the context files. + Implies _-s_. + +*--debug-parser*:: + Enable debug output for the internal policy parser. + Very noisy, useful to debug parsing failures. + +*-d, --disable*=_CHECKID_:: + Disable check with the given ID. + +*-e, --enable*=_CHECKID_:: + Enable check with the given ID. + +*-E, --only-enabled*:: + Only run checks that are explicitly enabled with the _--enable_ option. + +*--full-path*:: + Print full path for files. + +*-F, --fail*:: + Exit with a non-zero value if any issue was found. + +*-h, --help*:: + Display the menu. + +*-l, --level*=_LEVEL_:: + Only list errors with a severity level at or greater than LEVEL. + Options are _C_ (convention), _S_ (style), _W_ (warning), _E_ (error), _F_ (fatal error). + +*--scan-hidden-dirs*:: + Scan hidden directories. + By default hidden directories (like '.git') are skipped in recursive mode. + +*-s, --source*:: + Run in "source mode" to scan a policy source repository that is designed to compile into a full system policy. + +*-S, --summary*:: + Display a summary of issues found after running the analysis. + +*--summary-only*:: + Only display a summary of issues found after running the analysis. + Do not show the individual findings. + Implies _-S_. + +*-r, --recursive*:: + Scan recursively and check all SELinux policy files found. + +*-v, --verbose*:: + Enable verbose output. + +*-V, --version*:: + Show version information and exit. + + +== Exit Status + +*0*:: + Success. + Source policy files were successfully scanned. + +*70*:: + Failure. + Failed to parse or scan source policy files or issues were found while using the _--fail_ option. + + +== Configuration + +A global configuration is specified at the install prefix supplied to ./configure (typically /usr/local/etc). +This path can be overridden on the command line using the _-c_ option. + +Options specified on the command line override options from the config file. + +Lines staring with a pound (_#_) are ignored as comments. +Values are assigned to configuration keys via the equal sign (_=_). +See the global config file for more details on config file syntax. + + +== Severity Levels + +SELint messages are assocatied with a severity level, indicating the significance of the issue. +Available levels are listed below in increasing order of significance. + +=== X (extra) +Miscellaneous checks, mainly for policy introspection + +These must be explicitly enabled with their individual identifier. + +=== C (convention) +A violation of common style conventions + +=== S (style) +Stylistic "code smell" that may be associated with unintended behavior + +=== W (warning) +Non standard policy that may result in issues such as run time errors or security issues + +=== E (error) +Important issues that may result in errors at compile time or run time + +=== F (fatal error) +Error that prevents further processing + + +== SELint Exceptions + +To eliminate one or more checks on one line, add a comment containing a string in any of the following formats: + +* `selint-disable:E-003` +* `selint-disable: E-003` +* `selint-disable:E-003,E-004` +* `selint-disable: E-003, E-004` + +This is currently only supported in te and if files. + + +== Output + +SELint outputs messages in the following format: + + [filename]:[lineno]: ([SEVERITY LEVEL]): [MESSAGE] ([ISSUE ID]) + +For example: + + example.te:127: (E) Interface from module not in optional_policy block (E-001) + + +== Check IDs + +The following checks may be performed: + +=== X-001 +Unused interface or template declaration + +=== X-002 +AV rule with excluded source or target (can affect policy binary size) + + +=== C-001 +Violation of refpolicy te file ordering conventions + +=== C-004 +Interface does not have documentation comment + +=== C-005 +Permissions in av rule or class declaration not ordered + +=== C-006 +Declarations in require block not ordered + +=== C-007 +Redundant type specification instead of self keyword + +=== C-008 +Conditional expression identifier from foreign module + + +=== S-001 +Require block used instead of interface call + +=== S-002 +File context file labels with type not declared in module + +=== S-003 +Unnecessary semicolon + +=== S-004 +Template call from an interface + +=== S-005 +Declaration in interface + +=== S-006 +Bare module statement + +=== S-007 +Call to gen_context omits mls component + +=== S-008 +Unquoted gen_require block + +=== S-009 +Permission macro suffix does not match class name + +=== S-010 +Permission macro usage suggested + + +=== W-001 +Type or attribute referenced without explicit declaration + +=== W-002 +Type, attribute or role used but not listed in require block in interface + +=== W-003 +Unused type, attribute or role listed in require block + +=== W-004 +Potentially unescaped regex character in file contexts paths + +=== W-005 +Interface call from module not in optional_policy block + +=== W-006 +Interface call with empty argument + +=== W-007 +Unquoted space in argument of interface call + +=== W-008 +Allow rule with complement or wildcard permission + +=== W-009 +Module name does not match file name + +=== W-010 +Call to unknown interface + +=== W-011 +Declaration in require block not defined in own module + +=== W-012 +Conditional expression contains unknown identifier + +=== W-013 +Incorrect usage of audit_access permission + + +=== E-002 +Bad file context format + +=== E-003 +Nonexistent user listed in fc file + +=== E-004 +Nonexistent role listed in fc file + +=== E-005 +Nonexistent type listed in fc file + +=== E-006 +Declaration and interface with same name + +=== E-007 +Usage of unknown permission or permission macro + +=== E-008 +Usage of unknown class + +=== E-009 +Empty optional or require macro block + +=== E-010 +Usage of unknown simple m4 macro or stray word + + +=== F-001 +Policy syntax error prevents further processing + +=== F-002 +Internal error in SELint + + +== Reporting Bugs + +Report bugs at https://github.com/SELinuxProject/selint/issues + + +== Copyright + +Copyright \(C) 2019-present The SELint Contributors. + +Free use of this software is granted under the terms of the Apache License Version 2.0. diff --git a/man/selint.h2m b/man/selint.h2m deleted file mode 100644 index d79a2e02..00000000 --- a/man/selint.h2m +++ /dev/null @@ -1,5 +0,0 @@ -[AUTHOR] -Daniel Burgener - -[REPORTING_BUGS] -Report bugs at https://github.com/SELinuxProject/selint/issues diff --git a/selint.spec b/selint.spec index 71f225c6..78af7189 100644 --- a/selint.spec +++ b/selint.spec @@ -13,7 +13,7 @@ License: ASL 2.0 %forgemeta Source0: %{forgesource} -BuildRequires: autoconf autoconf-archive automake bison check check-devel flex gcc help2man libconfuse libconfuse-devel uthash-devel +BuildRequires: autoconf autoconf-archive automake bison check check-devel flex gcc asciidoctor libconfuse libconfuse-devel uthash-devel # pkgconfig Requires: libconfuse %if 0%{?fedora} || 0%{?rhel} >= 8