diff --git a/include/functions b/include/functions index b8a2891a..00c0b30d 100644 --- a/include/functions +++ b/include/functions @@ -213,7 +213,7 @@ # # Parameters : $1 = key # $2 = value - # Returns : True (0) or False (1) + # Returns : exit code (0 = True, 1 = False) # Usage : if CheckItem "key" "value"; then ....; fi ################################################################################ @@ -282,6 +282,8 @@ # Name : CleanUp() # Description : Delete PID and temporary files, stop execution (exit code 1) # + # Parameters : + # Returns : # Usage : this function is triggered by a manual break by user ################################################################################ @@ -298,7 +300,7 @@ # Name : ContainsString() # Description : Search a specific string (or regular expression) in another # - # Returns : True (0) or False (1) + # Returns : exit code (0 = True, 1 = False) # Usage : if ContainsString "needle" "there is a needle in the haystack"; echo "Found"; else "Not found"; fi ################################################################################ @@ -315,6 +317,8 @@ # Name : CountTests() # Description : Counter for the number of tests performed # + # Parameters : + # Returns : # Usage : Call CountTests to increase number by 1 ################################################################################ @@ -358,7 +362,7 @@ # Name : DirectoryExists() # Description : Check if a directory exists # - # Returns : True (0) or False (1) + # Returns : exit code (0 = True, 1 = False) # Usage : if DirectoryExists; then echo "it exists"; else echo "It does not exist"; fi ################################################################################ @@ -383,7 +387,7 @@ # Description : Show additional information on screen # # Input : $1 = text - # Returns : Nothing + # Returns : # Usage : Debug "More details" ################################################################################ @@ -413,7 +417,7 @@ # Name : DiscoverProfiles() # Description : Determine which profiles we have available # - # Returns : Nothing + # Returns : # Usage : DiscoverProfiles ################################################################################ @@ -612,7 +616,7 @@ # Name : DisplayWarning # Description : Show a warning on the screen # - # Input : $1 = text + # Parameters : $1 = text # Returns : ################################################################################ @@ -629,9 +633,11 @@ ################################################################################ # Name : Equals() - # Description : Compare two strings + # Description : Compare two strings after special characters were stripped # - # Returns : (0 - True, 1 - False) + # Parameters : $1 = string1 + # $2 = string2 + # Returns : exit code (0 = True, 1 = False) # Usage : if Equals "${MYDIR}" "/etc"; then echo "Found"; else "Not found"; fi ################################################################################ @@ -652,7 +658,7 @@ # Name : ExitClean() # Description : Perform a normal exit of the program, and clean up resources # - # Input : + # Parameters : # Returns : # Usage : ExitClean ################################################################################ @@ -669,8 +675,8 @@ # Name : ExitCustom() # Description : Perform a normal exit of the program, and clean up resources # - # Input : $1 = exit code (optional) - # Returns : Nothing + # Parameters : $1 = exit code (optional) + # Returns : # Usage : ExitCustom 35 ################################################################################ @@ -692,7 +698,7 @@ # Name : ExitFatal() # Description : Perform exit of the program (with code 1), clean up resources # - # Input : $1 = text string (optional) + # Parameters : $1 = text string (optional) # Returns : # Usage : ExitFatal ################################################################################ @@ -713,6 +719,8 @@ ################################################################################ # Name : FileExists() # Description : Determine if a file exists + # + # Parameters : $1 = path # Returns : 0 (found), 1 (not found) # FILE_FOUND (0:found, 1:not found) - deprecated usage ################################################################################ @@ -1177,7 +1185,8 @@ # Name : GetReportData() # Description : Request data from report # Returns : Data (when matches were found) - # Exit code: True (0) or False (1) when search was cancelled + # Returns : exit code (0 = True, 1 = False, meaning search was cancelled) + # stdout (output of search result) ################################################################################ GetReportData() { @@ -1207,7 +1216,6 @@ return 1 else ${AWKBINARY} -v pattern="^${KEY}" -F= '$1 ~ pattern {print $2}' ${REPORTFILE} | ${TRBINARY} -cd "${VALID_CHARS}" | ${TRBINARY} '[:blank:]' '__space__' - fi return 0 } @@ -1217,7 +1225,7 @@ # Name : HasData() # Description : Check for a filled variable # - # Returns : 0 = True, 1 = False + # Returns : exit code (0 = True, 1 = False) # Usage : if HasData "${FIND}"; then ################################################################################ @@ -1234,7 +1242,7 @@ # Name : InsertSection() # Description : Show a section block on screen # - # Returns : Nothing + # Returns : # Usage : InsertSection ################################################################################ @@ -1253,7 +1261,7 @@ # Name : InsertPlugionSection() # Description : Insert section block for plugins (different color) # - # Returns : Nothing + # Returns : # Usage : InsertPluginSection ################################################################################ @@ -1270,8 +1278,10 @@ ################################################################################ # Name : IsContainer() # Description : Determine if we are running in a container - # Returns : Exit code (0 = true, 1 = false) - # CONTAINER_TYPE + # + # Parameters : + # Returns : exit code (0 = true, 1 = false) + # variable: CONTAINER_TYPE ################################################################################ IsContainer() { @@ -1304,7 +1314,9 @@ ################################################################################ # Name : IsDebug() # Description : Check if --debug option is used to show more details - # Returns : 0 (True) or 1 (False) + # + # Parameters : + # Returns : exit code (0 = True, 1 = False) ################################################################################ IsDebug() { @@ -1316,7 +1328,8 @@ # Name : IsDeveloperMode() # Description : Check if we are in development mode (--developer) # - # Returns : 0 (True) or 1 (False) + # Parameters : + # Returns : exit code (0 = True, 1 = False) # Notes : This is set with command line option or as a profile setting ################################################################################ @@ -1329,7 +1342,8 @@ # Name : IsDeveloperVersion() # Description : Check if this version is development or stable release # - # Returns : 0 (True) or 1 (False) + # Parameters : + # Returns : exit code (0 = True, 1 = False) ################################################################################ IsDeveloperVersion() { @@ -1341,7 +1355,7 @@ # Name : IsEmpty() # Description : Check for variable that has no data in it # - # Returns : 0 = True, 1 = False + # Returns : exit code (0 = True, 1 = False) # Usage : if IsEmpty "${FIND}"; then ################################################################################ @@ -1465,7 +1479,7 @@ ################################################################################ # Name : IsNotebook # Description : Check if file or directory is owned by root - # Returns : 0 (true), 1 (false), or 255 (unknown) + # Returns : exit code (0 = True, 1 = False, 255 = Unknown) ################################################################################ IsNotebook() { @@ -1521,7 +1535,9 @@ ################################################################################ # Name : IsVerbose() # Description : Check if --verbose option is used to show more details on screen - # Returns : 0 (true) or 1 (false) + # + # Parameters : + # Returns : exit code (0 =true, 1 =false) ################################################################################ IsVerbose() { @@ -1532,9 +1548,11 @@ ################################################################################ # Name : IsVirtualMachine() # Description : Determine whether it is a virtual machine - # Returns : ISVIRTUALMACHINE (0-2) - # VMTYPE - # VMFULLTYPE + # Parameters : + # Returns : exit code (0 = True, 1 = False, 2 = Unknown) + # variable: ISVIRTUALMACHINE (0-2) + # variable: VMTYPE + # variable: VMFULLTYPE ################################################################################ IsVirtualMachine() { @@ -1750,7 +1768,7 @@ # Name : IsWorldReadable() # Description : Determines if a file is readable for all users (world) # - # Input : path (string) + # Input : $1 = path (string) # Returns : exit code (0 = readable, 1 = not readable, 255 = error) # Usage : if IsWorldReadable /etc/motd; then echo "File is readable"; fi ################################################################################ @@ -1776,7 +1794,7 @@ # Name : IsWorldExecutable() # Description : Determines if a file is executable for all users (world) # - # Input : path (string) + # Input : $1 = path (string) # Returns : exit code (0 = executable, 1 = not executable, 255 = error) # Usage : if IsWorldExecutable /bin/ps; then echo "File is executable"; fi ################################################################################ @@ -1803,7 +1821,7 @@ # Name : IsWorldWritable() # Description : Determines if a file is writable for all users # - # Input : path + # Parameters : $1 = path # Returns : exit code (0 = writable, 1 = not writable, 255 = error) # Usage : if IsWorldWritable /etc/motd; then echo "File is writable"; fi ################################################################################ @@ -1828,8 +1846,8 @@ # Name : LogText() # Description : Function logtext (redirect data ($1) to log file) # - # Input : $1 = text (string) - # Returns : Nothing + # Parameters : $1 = text (string) + # Returns : # Usage : LogText "This line goes into the log file" ################################################################################ @@ -1898,6 +1916,7 @@ ################################################################################ # Name : ParseProfiles() # Description : Check file permissions and parse data from profiles + # Parameters : # Returns : ################################################################################ @@ -1910,8 +1929,9 @@ ################################################################################ # Name : ParseTestValues() # Description : Parse values from a specific test - # Inputs : service (e.g. ssh) - # Returns : CHECK_VALUES_ARRAY + # + # Parameters : $1 = service (e.g. ssh) + # Returns : CHECK_VALUES_ARRAY variable ################################################################################ ParseTestValues() { @@ -1965,7 +1985,8 @@ ################################################################################ # Name : ParseNginx() # Description : Parse nginx configuration lines - # Input : $1 = file (should be readable and tested upfront) + # + # Parameters : $1 = file (should be readable and tested upfront) # Returns : ################################################################################ @@ -2179,12 +2200,15 @@ ################################################################################ # Name : PortIsListening() # Description : Check if machine is listening on specified protocol and port - # Returns : exit code 0 (listening) or 1 (not listening) + # + # Parameters : $1 = protocol + # $2 = port + # Returns : exit code (0 = listening, 1 = not listening, 255 = can't perform test) # Usage : if PortIsListening "TCP" 22; then echo "Port is listening"; fi ################################################################################ PortIsListening() { - if [ "${LSOFBINARY}" = "" ]; then + if [ -z "${LSOFBINARY}" ]; then return 255 else if [ $# -eq 2 ] && [ $1 = "TCP" -o $1 = "UDP" ]; then @@ -2209,7 +2233,7 @@ # Name : Progress() # Description : Displays progress on screen with dots # - # Input : --finish or text (string) + # Parameters : $1 = --finish or text (string) # Returns : # Tip : Use this function from Register with the --progress parameter ################################################################################ @@ -2235,8 +2259,9 @@ ################################################################################ # Name : RandomString() # Description : Displays progress on screen with dots - # Input : Amount of characters (optional) - # Returns : RANDOMSTRING + # + # Parameters : $1 = number (amount of characters, optional) + # Returns : RANDOMSTRING variable # Usage : RandomString 32 ################################################################################ @@ -2256,7 +2281,9 @@ ################################################################################ # Name : Readonly() # Description : Mark a variable as read-only data - # Returns : nothing + # + # Returns : + # Notes : new function, not in use yet ################################################################################ Readonly() { @@ -2275,6 +2302,8 @@ ################################################################################ # Name : Register() # Description : Register a test and see if it has to be run + # + # Parameters : multiple, see test # Returns : SKIPTEST (0 or 1) ################################################################################ @@ -2468,7 +2497,9 @@ ################################################################################ # Name : RemoveColors() - # RemoveColors Clear color settings for --no-colors (see include/consts) + # Description : Disabled colors by overriding them (defined in include/consts) + # + # Notes : Can be activated using --no-colors ################################################################################ RemoveColors() { @@ -2506,6 +2537,9 @@ ################################################################################ # Name : RemovePIDFile() # Description : When defined, remove the file storing the process ID + # + # Parameters : + # Returns : ################################################################################ # Remove PID file @@ -2555,6 +2589,9 @@ ################################################################################ # Name : Report() # Description : Store data in the report file + # + # Parameters : $1 = data (format: key=value) + # Returns : ################################################################################ Report() { @@ -2568,7 +2605,7 @@ # smaller atomic tests are performed. For example sysctl keys, # and SSH settings. # - # Input : + # Parameters : # Returns : # Notes : Need to check for values (strip out semicolons from values) # Only add fields which are filled in @@ -2633,11 +2670,10 @@ # # Parameters : $1 = test ID + colon + 2 numeric characters (TEST-1234:01) # $2 = string (text) + # Notes : Allow this function with only 1 parameter in strict mode with ${2-Text} ################################################################################ - # Log exceptions ReportException() { - # Allow this function with only 1 parameter in strict mode with ${2-Text} Report "exception_event[]=$1|${2-NoInfo}|" LogText "Exception: test has an exceptional event ($1) with text ${2-NoText}" } @@ -2668,6 +2704,7 @@ # * url:https://example.org/how-to-solve-link # * text:Additional explanation # * - (dash) for none + # Returns : ################################################################################ ReportSuggestion() { @@ -2686,17 +2723,19 @@ ################################################################################ # Name : ReportWarning() # Description : Log a warning to the report file + # + # Parameters : $1 = test ID + # $2 = message (optional) + # $3 = details (optional) + # $4 = possible solution (optional) + # Returns : ################################################################################ ReportWarning() { TOTAL_WARNINGS=$((TOTAL_WARNINGS + 1)) - # Old style - # + # Old style used L/M/H level as second parameter. This is deprecated as of 3.x if [ "$2" = "L" -o "$2" = "M" -o "$2" = "H" ]; then - if [ $# -ge 1 ]; then TEST="$1"; fi - if [ $# -ge 2 ]; then DETAILS="$2"; fi - if [ $# -ge 3 ]; then MESSAGE="$3"; fi - SOLUTION="-" + ExitFatal "Deprecated usage of ReportWarning() function" else # New style warning format: #
@@ -2725,7 +2764,7 @@ # Description : Test provided string to see if it contains unwanted characters # # Input : string + optional class (parameter 2) - # Returns : 0 (input considered to be safe) or 1 (validation failed) + # Returns : exit code (0 = input considered to be safe, 1 = validation failed) ################################################################################ SafeInput() { @@ -2754,6 +2793,8 @@ # Name : SafeFile() # Description : Check if a file is safe to use # + # Parameters : $1 = file name + # Returns : exit code (0 = OK, 1 = issue) ################################################################################ SafeFile() { @@ -2805,6 +2846,8 @@ # Name : SafePerms() # Description : Check if a file has safe permissions to be used # + # Parameters : $1 = file name + # $2 = type of file (optional) # Returns : 0 (file permissions OK) or break ################################################################################ @@ -2962,7 +3005,7 @@ # Name : ShowComplianceFinding() # Description : Display a section of a compliance standard which is not fulfilled # - # Input : + # Parameters : # Returns : ################################################################################ @@ -3048,7 +3091,7 @@ # Name : ShowSymlinkPath() # Description : Check if we can find the path behind a symlink # - # Input : $1 = file (string) + # Parameters : $1 = file (string) # Returns : FOUNDPATH (0 not found, 1 found path), SYMLINK (new path) ################################################################################ @@ -3370,6 +3413,41 @@ # steps. If they still get used, they will trigger errors on screen. ################################################################################ + counttests() { + DisplayWarning "Deprecated function used (counttests)" + if IsDeveloperMode; then Debug "Warning: old counttests function is used. Please replace any reference with CountTests."; fi + CountTests + } + + logtext() { + DisplayWarning "Deprecated function used (logtext)" + if IsDeveloperMode; then Debug "Warning: old logtext function is used. Please replace any reference with LogText."; fi + LogText "$1" + } + + logtextbreak() { + DisplayWarning "Deprecated function used (logtextbreak)" + if IsDeveloperMode; then Debug "Warning: old logtextbreak function is used. Please replace any reference with LogTextBreak."; fi + LogTextBreak "$1" + } + + report() { + DisplayWarning "Deprecated function used (report)" + if IsDeveloperMode; then Debug "Warning: old report function is used. Please replace any reference with Report."; fi + Report "$1" + } + + wait_for_keypress() { + DisplayWarning "Deprecated function used (wait_for_keypress)" + if IsDeveloperMode; then Debug "Warning: old wait_for_keypress function is used. Please replace any reference with WaitForKeyPress."; fi + WaitForKeyPress + } + + ShowResult() { + DisplayWarning "Deprecated function used (ShowResult)" + if IsDeveloperMode; then Debug "Warning: old ShowResult() function is used. Please replace any reference with WaitForKeyPress."; fi + } + #================================================================================ # Lynis is part of Lynis Enterprise and released under GPLv3 license