From af0f418b7f5fd677cf153b97c7a8f980b5728aaf Mon Sep 17 00:00:00 2001 From: Jake Hunsaker Date: Thu, 21 May 2020 16:32:06 -0400 Subject: [docs] Add manpage for sos clean Adds a manpage for `sos clean`, with a link for `sos mask`. Updates `man sos` as well to include the options moved into the global group as part of the SoSCleaner patchset. Related: #1987 Signed-off-by: Jake Hunsaker --- man/en/sos-clean.1 | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ man/en/sos-mask.1 | 1 + man/en/sos.1 | 50 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 115 insertions(+) create mode 100644 man/en/sos-clean.1 create mode 120000 man/en/sos-mask.1 (limited to 'man') diff --git a/man/en/sos-clean.1 b/man/en/sos-clean.1 new file mode 100644 index 00000000..729c812f --- /dev/null +++ b/man/en/sos-clean.1 @@ -0,0 +1,64 @@ +.TH SOS CLEAN 1 "Thu May 21 2020" +.SH NAME +sos clean - Obfuscate sensitive data from one or more sosreports +.SH SYNOPSIS +.B sos clean TARGET [options] + [\-\-map] + [\-\-jobs] + [\-\-no-update] + +.SH DESCRIPTION +\fBsos clean\fR or \fBsos mask\fR is an sos subcommand used to obfuscate sensitive information from +previously generated sosreports that is not covered by the standard plugin-based post +processing executed during report generation, for example IP addresses. +.LP +Data obfuscated via this utility is done so consistently, meaning for example an IP address of +192.168.1.1 in an unprocessed sosreport that gets obfuscated to, for example, 100.0.0.1, will be +changed to 100.0.0.1 in all occurences found in the report. + +Additionally, by default all such obfuscations are stored in "maps" that will be persistently +saved to /etc/sos/cleaner/default_mappings and be re-used on subsequent runs. +.LP +This utility may also be used in-line with \fBsos report\fR and \fB sos collect\fR by specifying the +\fB\-\-clean\fR or \fB\-\-mask\fR option. +.LP +When called directly via \fBsos clean\fR, the obfuscated archive is written as an additional file, +meaning the original unprocessed report still remains on the filesystem. When called via \fBreport\fR or +\fBcollect\fR, the changes are done in-line and thus only an obfuscated archive is written and available. +In either case, a mapping file containing the relationships between unprocessed and obfuscated elements will +be written in the same location as the resulting archive. This mapping file should be kept private +by system administrators. + +.SH REQUIRED ARGUMENTS +.B TARGET +.TP +The path to the archive that is to be obfuscated. This may be an archive or an unbuilt sos temporary +directory. If an archive, it will first be extracted and then after obfuscation is complete re-compressed +using the same compression method as the original. + +.SH OPTIONS + +.TP +.B \-\-map FILE +Provide a location to a valid mapping file to use as a reference for existing obfuscation pairs. +If one is found, the contents are loaded before parsing is started. This allows consistency between +runs of this command for obfuscated pairs. By default, sos will write the generated private map file +to /etc/sos/cleaner/default_mapping so that consistency is maintained by default. Users may use this +option to reference a map file from a different run (perhaps one that was done on another system). + +Default: /etc/sos/cleaner/default_mapping +.TP +.B \-\-jobs JOBS +The number of concurrent archives to process, if more than one. If this utility is called by +\fBsos collect\fR then the value of the jobs option for that utility will be used here. + +Default: 4 +.TP +.B \-\-no-update +Do not write the mapping file contents to /etc/sos/cleaner/default_mapping +.SH MAINTAINER +.nf +Jake Hunsaker +.fi +.SH AUTHORS & CONTRIBUTORS +See \fBAUTHORS\fR file in the package documentation. diff --git a/man/en/sos-mask.1 b/man/en/sos-mask.1 new file mode 120000 index 00000000..1a9baf9d --- /dev/null +++ b/man/en/sos-mask.1 @@ -0,0 +1 @@ +sos-clean.1 \ No newline at end of file diff --git a/man/en/sos.1 b/man/en/sos.1 index 0444dba4..af1a5287 100644 --- a/man/en/sos.1 +++ b/man/en/sos.1 @@ -49,10 +49,57 @@ See \fBsos collect --help\fR and \fBman sos-collect\fR for more information. May also be invoked via the alias \fBsos collector\fR or the deprecated command \fBsos-collector\fR. +.TP +.B clean|mask +This subcommand takes input of either 1) an sosreport tarball, 2) a collection +of sosreport tarballs such as from \fBcollect\fR, or 3) the unpackaged +directory of an sosreport and obfuscates potentially sensitive system information +that is not covered by the standard postprocessing of \fBsos report\fR. + +Such data includes IP addresses, networks, MAC addresses, and more. Data obfuscated +by this command will remain consistent throughout the report and across reports provided +in the same invocation. Additionally, care is taken to maintain network topology relationships +between matched data items. + +See \fB sos clean --help\fR and \fBman sos-clean\fR for more information. + +May be invoked via either \fBsos clean\fR, \fBsos mask\fR, or via the \fB--clean\fR or \fB --mask\fR options +for \fBreport\fR and \fBcollect\fR. + .SH GLOBAL OPTIONS sos components provide their own set of options, however the following are available to be set across all components. +.B \-\-batch +Do not prompt interactively, user will not be prompted for any data +.TP +.B \--encrypt-key KEY +Encrypts the resulting archive that sosreport produces using GPG. KEY must be +an existing key in the user's keyring as GPG does not allow for keyfiles. +KEY can be any value accepted by gpg's 'recipient' option. + +Note that the user running sosreport must match the user owning the keyring +from which keys will be obtained. In particular this means that if sudo is +used to run sosreport, the keyring must also be set up using sudo +(or direct shell access to the account). + +Users should be aware that encrypting the final archive will result in sos +using double the amount of temporary disk space - the encrypted archive must be +written as a separate, rather than replacement, file within the temp directory +that sos writes the archive to. However, since the encrypted archive will be +the same size as the original archive, there is no additional space consumption +once the temporary directory is removed at the end of execution. + +This means that only the encrypted archive is present on disk after sos +finishes running. + +If encryption fails for any reason, the original unencrypted archive is +preserved instead. +.TP +.B \--encrypt-pass PASS +The same as \--encrypt-key, but use the provided PASS for symmetric encryption +rather than key-pair encryption. +.TP .B \--config-file CONFIG Specify alternate configuration file. .TP @@ -72,6 +119,9 @@ additional debugging messages. .B \-q, \--quiet Only log fatal errors to stderr. .TP +.B \-z, \-\-compression-type {auto|xz|gzip} +Compression type to use when compression the final archive output +.TP .B \--help Display usage message. .SH MAINTAINER -- cgit