SCA Pattern Development
Documentation

Pattern Basics

The Supportconfig Analysis (SCA) appliance and command line tool use scripts or programs to parse supportconfig archive files looking for specific known issues. The scripts or programs are patterns. You can create your own custom patterns for local use. The Supportconfig Analysis pattern database is used to manage and create pattern templates to speed up development time.

Pattern library documentation is available for Python and Perl. Python is the preferred language.

Tutorials

The following tutorials demonstrate the details of pattern development.

Pattern Writing Tutorial #1
Pattern Writing Tutorial #2

Pattern Requirements

A Supportconfig Analysis pattern has the following requirements:

Creating a Pattern

  1. Read the TID, associated bug(s) and any other documentation to understand the issue
  2. Write the pseudocode code that identifies the issue from supportconfig text files
  3. Run patgen to create your initial python script. It will update the local cloned git repositories, check for duplicate patterns for the TID number, and validate all solulition links.

  4. NOTE: If you don't use patgen, run gitpatterns and chktid <tid_number> to search for duplicate patterns.

  5. Modify your script to fine tune its analysis of the supportconfig files
  6. Test your pattern with pat against a supportconfig archive with and without the issue
  7. Fix any bugs in the pattern
  8. Submit the pattern upstream in GitHub

Refer to the patgen help screen.
##################################################
# SCA Tool Python Pattern Generator v1.0.10
##################################################
Usage:
  patgen [OPTIONS] 

Description:
  Used to create an initial python3 script template for an SCA pattern. Modify the template script
  to accurately identify the issue and record it on the SCA Report as needed.

  Ordering, Stacked: kernel > package > service > conditions
  Ordering, Flat:    kernel   package   service   conditions

  Documentation: /usr/share/doc/packages/sca-patterns-devel/index.html

OPTIONS
  -c <0-3>, --conditions=<0-3>       Number of conditional functions to include, default=0
  -k , --kernel-version=   The kernel's version where the issue is fixed
  -r , --rpm=            The affected RPM package name
  -o, --no-validation                Ignore invalid solution links
  -p , --package-version=  The package's version where the issue is fixed
  -s , --service=        The systemd service name affected
  -u <[tag=]url>, --url=<[tag=]url>  Additional solution link URL. You can also enter a CVE number like "CVE-2022-23303"
  -f, --flat                         All requested conditions are tested independently and not included in stacked order
  -d, --no-duplicates                Don't check for duplicate patterns

METADATA
  class:        SLE,HAE,SUMA,Security,Custom
  category:     Category name string
  component:    Component name string
  filename:     Pattern filename (TID number will be added automatically)
  tid#:         TID number only
  bug#:         Bug number only (optional)

Testing a Pattern

Once you have finished your pattern, you can test its effectiveness with a command line tool called pat.

  1. Copy and extract the supportconfig archives to test against into the archive directory (Default: /var/opt/patdevel/archives)
  2. If you already have supportconfig archives extracted in a different location, run pat -a <path_to_archives> to set the pattern tester archive location
  3. Change to the directory where your pattern is located (ie ~/patterns)
  4. Run pat -v <path_to_archives> to check the pattern against all supportconfigs in the PATDEV_ARCH_DIR directory as defined in /etc/opt/patdevel/patdev.conf.
  5. Compare the output to the Pattern Requirements above
  6. Review the pat output for any errors

Pattern Submission

  1. If you don't already have one, create a personal GitHub account and login
  2. Go to the pattern repository to which you want to submit additions or changes. The most common pattern repositories are: sca-patterns-sle15, sca-patterns-sle12 and sca-patterns-sle11.
  3. Fork the repository so you have your own copy to modify (See GitHub Docs: Fork a Repo)
  4. Clone the forked repository to your /var/opt/patdevel/forks directory
  5. Once you have developed and tested your patterns, copy them to the appropriate location in the forked repository
  6. Update the spec/*.changes file with a description of your pattern(s) or changes
  7. Commit your changes to your forked repository
  8. Create a pull request from the associated upstream repository comparing changes in your forked repository (See GitHub Docs: Creating a Pull Request from a Fork)
  9. Wait for the changes to be merged into the upstream repository