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:
- Be executable, so bash can execute it by referencing the filename only
- Most patterns are written in Python. It has the most current libraries for pattern development.
- Accepts a -p start up parameter with the value of the path to the extracted supportconfig archive
- Writes a case sensitive, order dependent information string to stdout
META_CLASS=<string>|META_CATEGORY=<string>|META_COMPONENT=<string>|PATTERN_ID=<pattern_filename>|PRIMARY_LINK=META_LINK_<TAG>|OVERALL=[0-6]|OVERALL_INFO=<message string>|META_LINK_<TAG>=<URL>[|META_LINK_<TAG>=<URL>]
- A pattern supports a maximum of 12 solution links - one TID, one BUG and 10 custom links
- Provide at least one solution link
- Set the OVERALL status with the Core.updateStatus function using one of the following:
STATUS_TEMPORARY = -2
STATUS_PARTIAL = -1
STATUS_SUCCESS = 0
STATUS_RECOMMEND = 1
STATUS_PROMOTION = 2
STATUS_WARNING = 3
STATUS_CRITICAL = 4
STATUS_ERROR = 5
STATUS_IGNORE = 6
- Set the OVERALL_INFO value to the report's display string
Creating a Pattern
- Read the TID, associated bug(s) and any other documentation to understand the issue
- Write the pseudocode code that identifies the issue from supportconfig text files
- 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.
NOTE: If you don't use patgen, run gitpatterns and chktid <tid_number> to search for duplicate patterns.
- Modify your script to fine tune its analysis of the supportconfig files
- Test your pattern with pat against a supportconfig archive with and without the issue
- Fix any bugs in the pattern
- 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.
- Copy and extract the supportconfig archives to test against into the archive directory (Default: /var/opt/patdevel/archives)
- If you already have supportconfig archives extracted in a different location, run pat -a <path_to_archives> to set the pattern tester archive location
- Change to the directory where your pattern is located (ie ~/patterns)
- 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.
- Compare the output to the Pattern Requirements above
- Review the pat output for any errors
Pattern Submission
- If you don't already have one, create a personal GitHub account and login
- 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.
- Fork the repository so you have your own copy to modify (See GitHub Docs: Fork a Repo)
- Clone the forked repository to your /var/opt/patdevel/forks directory
- Once you have developed and tested your patterns, copy them to the appropriate location in the forked repository
- Update the spec/*.changes file with a description of your pattern(s) or changes
- Commit your changes to your forked repository
- 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)
- Wait for the changes to be merged into the upstream repository