Obfuscate an sos Report with sos clean

An old ticket surfaces with a full sos report attached, and nobody remembers scrubbing it. sos clean produces a second, obfuscated copy while leaving the original alone, and it replaces sensitive values consistently: the same address or hostname gets the same replacement everywhere it appears. It is a strong first pass before a report leaves the building, not a guarantee that every secret is gone.

Allow about 10 minutes for a normal report, plus time to inspect the result. You need the sosreport package and an archive or unbuilt report directory. Run the cleaning command with elevated privileges where the installed sos configuration requires it. On the tested system, the package is sosreport 4.10.2-0ubuntu0~24.04.1.

Checkpoint 1: protect the input and its mapping

Cleaning a report is a data-handling operation. Work on a copy in a directory with restricted access, and do not upload the mapping file. The mapping records the relationship between original and obfuscated values and can undo the privacy benefit of the cleaned archive.

Make a private working directory and copy the report into it:

install -d -m 700 /var/tmp/sos-clean-work
cp -- /path/to/original-sos-report.tar.xz /var/tmp/sos-clean-work/input.tar.xz
chmod 600 /var/tmp/sos-clean-work/input.tar.xz
ls -l /var/tmp/sos-clean-work/input.tar.xz

Replace /path/to/original-sos-report.tar.xz with the real path. Keep the original elsewhere until the cleaned archive has passed your review. Do not point the command at a report received from an untrusted party while logged in as root without first assessing the archive and the installed sos version. Archive extraction is a security boundary, not just a compression detail.

Checkpoint 2: run the default cleaning pass

Use sos clean with the archive as its required target. The command detects the archive type by default, extracts it temporarily, obfuscates supported values, and writes an additional archive. The original input remains in place.

sudo sos clean /var/tmp/sos-clean-work/input.tar.xz

Read the command's output for the path of the new archive and mapping file. Then list the work directory:

find /var/tmp/sos-clean-work -maxdepth 1 -type f -printf '%f\n' | sort

By default, sos also persists mappings in /etc/sos/cleaner/default_mapping for reuse on later runs. That improves consistency between reports, but it is sensitive state. If you are handling a one-off report and do not want new pairs added to the default map, add --no-update:

sudo sos clean --no-update /var/tmp/sos-clean-work/input.tar.xz

An existing mapping can be supplied explicitly with --map-file. Make its permissions restrictive and treat it as confidential:

sudo sos clean --no-update \
  --map-file /secure/path/known-cleaner-map \
  /var/tmp/sos-clean-work/input.tar.xz

Checkpoint 3: add organisation-specific values

The normal parsers cover common network and identity data. Add domains or keywords that are specific to your organisation. Domains are comma-delimited, and subdomains of a supplied domain are included:

sudo sos clean --no-update \
  --domains example.org,example.net \
  --keywords INTERNAL_PROJECT,customer-token \
  /var/tmp/sos-clean-work/input.tar.xz

For a longer list, put one keyword on each line and pass the file with --keyword-file:

install -m 600 /dev/null /var/tmp/sos-clean-work/keywords.txt
# Edit the file, placing one keyword on each line.
sudo sos clean --no-update \
  --keyword-file /var/tmp/sos-clean-work/keywords.txt \
  /var/tmp/sos-clean-work/input.tar.xz

Keyword matching also covers substring matches. Use distinctive values rather than short fragments that could alter unrelated text.

What not to switch off casually

--disable-parsers accepts parser names such as hostname, ip, ipv6, mac, keyword and username. Disabling one can leave exactly the sensitive data you intended to remove. Likewise, --skip-cleaning-files and its alias --skip-masking-files exclude named files inside the archive; globs are supported. Use either only after reviewing the excluded content.

Binary files cannot be obfuscated. By default encountered binary files are removed. --keep-binary-files retains them, which can reintroduce sensitive data, so use it only when you have reviewed the resulting archive.

Checkpoint 4: inspect before sharing

Do not assume a successful exit means the archive is safe. Extract the cleaned archive into a fresh private directory and search for known originals, organisation-specific names and secret-shaped strings. Use the archive's actual path from the command output:

mkdir -m 700 /var/tmp/sos-clean-work/review
tar -xf /var/tmp/sos-clean-work/cleaned-report.tar.xz \
  -C /var/tmp/sos-clean-work/review
rg -n -i 'example\.org|192\.0\.2\.10|customer-token' \
  /var/tmp/sos-clean-work/review || true

The placeholder values above are examples. Replace them with values that must not remain. Also inspect filenames, certificates, binary files and the mapping file. A mapping file belongs in the restricted working area, never in the upload bundle.

Recovery and repeat runs

Direct cleaning writes a new archive, so recovery is straightforward: remove or quarantine the cleaned output and keep the original. If you used the default mapping, remove only newly created mapping entries through your normal configuration-management or administrator process; do not delete a shared map that other reports still need. For a repeatable workflow, keep a controlled map with --map-file, use --no-update, and record the exact command and sos version alongside the review notes.

Done means

• The original report is preserved and the cleaned archive is a separate file.
• The mapping file and working directory are readable only by authorised administrators.
• Organisation-specific domains and keywords were included where needed.
• No parser or file was skipped without a documented review.
• The cleaned archive was extracted and searched for representative original values before sharing.