Sanitise an sos Report Before Sharing It with sos clean

Use sos clean to make a separate, obfuscated copy of an existing sos report. This is useful when a support case needs logs and command output but the archive contains hostnames, addresses, usernames or another identifier that should not leave your environment. The cleaner uses the same replacement for repeated values, so a report remains useful for troubleshooting.

This guide targets sosreport 4.10.2, installed here as sosreport 4.10.2-0ubuntu0~24.04.1. The local sos-clean(1) page is dated 2020, while the installed help also exposes newer options. Check the help on the machine that will do the work if the package version differs.

Time: allow 5 to 15 minutes, plus time to inspect the resulting archive. You need the source report, enough free space for extraction and recompression, and a private working directory. Root is not normally needed for a user-owned report when you use --no-update; reading or writing the default map under /etc/sos/cleaner may require elevated privileges.

Checkpoint 1: identify the input and version

1. Choose a copy of the report, not the only original, and record its path.

readonly REPORT="/path/to/sos-report.tar.xz"
test -r "$REPORT" && printf 'Input: %s\n' "$REPORT"
sos --version
sos clean --help

In the installed 4.10.2 command, the target may be a directory or an archive. The cleaner detects report and collection archives, and accepts an explicit --archive-type when detection is unreliable. For a normal report, start with the default auto. Do not use --archive-type data-dir for an archive: that value describes a plain directory.

Checkpoint 2: make a disposable working copy

1. Copy the input into a private directory with enough free space for a second result.

umask 077
WORK="$(mktemp -d /tmp/sos-clean.XXXXXX)"
cp --reflink=auto -- "$REPORT" "$WORK/input-report.tar.xz"
printf 'Working copy: %s\n' "$WORK/input-report.tar.xz"
ls -lh -- "$WORK/input-report.tar.xz"

The command writes an additional obfuscated result when run directly, so the original report remains available. Keeping the original outside the temporary directory gives you a clear recovery path: discard the result and repeat from the untouched source. Remove the temporary directory only after you have finished reviewing both the result and its private map.

Checkpoint 3: run the cleaner without changing the shared map

1. Clean the working copy with the default parsers and suppress the persistent map update.

sos clean "$WORK/input-report.tar.xz" \
  --batch \
  --no-update \
  --archive-type auto

--batch avoids the confirmation prompt in this non-interactive example. --no-update stops this run writing new pairs to /etc/sos/cleaner/default_mapping. The command extracts an archive, obfuscates it and recompresses it using the original compression method. Its final lines identify the obfuscated archive and the private mapping file. Save those paths; the exact output name depends on the input and installed version.

Without --no-update, the default mapping is reused on later runs and new replacements are added to it. That consistency is helpful when several reports describe the same system, but it is a deliberate system-wide state change. Use elevated privileges only when that shared map is an intentional part of your administration process.

Checkpoint 4: add organisation-specific secrets carefully

1. Put one additional keyword per line in a private file, then run the cleaner again from a fresh copy.

KEYWORDS="$WORK/keywords.txt"
printf '%s\n' 'EXAMPLE_INTERNAL_NAME' 'EXAMPLE_CASE_TOKEN' > "$KEYWORDS"
chmod 600 "$KEYWORDS"

sos clean "$WORK/input-report.tar.xz" \
  --batch \
  --no-update \
  --keyword-file "$KEYWORDS"

Keywords are replaced both as standalone words and inside longer strings. That broad matching can remove more context than expected, so use distinctive values and inspect the result. The command also accepts a comma-delimited --keywords value, but a file avoids putting sensitive text in shell history. The installed 4.10.2 help additionally lists --usernames and certificate handling; consult that help before relying on options absent from the local manpage.

Checkpoint 5: review before transmission

1. Inspect the generated archive as an untrusted transformation, then search for values that must not remain.

# Replace RESULT with the path printed by sos clean.
RESULT="/path/printed/by/sos-clean"
tar -tf "$RESULT" | sed -n '1,40p'
tar -xOf "$RESULT" > /dev/null 2>/dev/null || true
grep -R -n --binary-files=without-match \
  -e '192\.0\.2\.10' \
  -e 'EXAMPLE_INTERNAL_NAME' \
  /path/to/reviewed/extracted/report

The last search is only an example: replace it with real values known to be present in the original, and search the extracted result with the tools appropriate for its archive layout. A clean exit does not prove that every secret was found or removed. The sos project describes cleaning as best effort, and binary files cannot be obfuscated. By default encountered binary files are removed; --keep-binary-files keeps them but may preserve sensitive data, so use it only after a separate review.

Do not use --disable-parsers or --skip-cleaning-files merely to make a run complete. The former can leave whole classes of identifiers untouched, while the latter deliberately excludes named files or globs. If you used either option for a known safe reason, document the exception beside the archive and review the skipped content manually.

Common traps and recovery

• Wrong archive type: retry from the original working copy with the appropriate value from auto, report or collect. Use data-dir only for a plain directory and tarball only for a generic tar archive.
• Inconsistent replacements: reuse a valid mapping with --map-file, or allow the default map to be updated on purpose. Do not share that map with the cleaned report.
• Unexpectedly missing files: check whether binary files were removed. Re-run with --keep-binary-files only when you accept the confidentiality risk and can inspect those files.
• Need to undo the run: delete only the generated archive and its map, then start again from the untouched original. The direct command does not rewrite the original report.