Skip to content

README.md

Latest commit

 

History

History
85 lines (64 loc) · 8.9 KB

README.md

File metadata and controls

85 lines (64 loc) · 8.9 KB
Raw

susemanager-api

Scripts using the SUSE Manager API

These scripts all use the SUSE Manager API to do common tasks and extract information from any SUSE Manager instance.

I get asked about how to use the API quite frequently, so I decided to make a few working examples (based on scripts I wrote waaaay back in 2014 -- I'm getting old!) and share them with the world.

Prefer dashboards? There's also a Grafana dashboard with inventory, action and per-group security reports, built on SUSE Multi-Linux Manager's reporting database. See the Grafana dashboard page for screenshots, setup and how to test it locally.

General usage instructions

The older scripts with the URL to the SUMA server hardcoded in the first lines were moved to the "classic" folder. Please change that before using.

All scripts now have standardized parameters for specifying the server name (-s), user (-u), password (-p) and URL (--url). If you just specify the server name, it'll assume the default URL always (https:///api/rpc).

By default the CA verification will be disabled, but you can force it with "--verify".

All scripts have a -h/--help parameter.

Most of the actions will require a regular SUMA user that's at least capable of reading information (Read-only user). The runscripts_sm script requires an admin user, as it is indeed creating/scheduling jobs.

These scripts are meant to make it easy to customize SUSE Multi-Linux Manager/Uyuni to your environment, and mainly so you can learn how to do it.

The complete SUSE Multi-Linux Manager API reference is available at: https://documentation.suse.com/suma/5.1/api/suse-manager/index.html

Currently available scripts

  • add_to_group.py: adds a system to System Group
  • apply_state.py: apply a named salt state to a system
  • create_activationkey.py: create a new activation key
  • create_group.py: create a new group
  • create_user.py: create a new user
  • check_activationkey.py: this will search for a named activation key and report if it exists or not.
  • delete_system.py: delete a system profile
  • delete_user.py: delete a user
  • get_all_eventhistory.py: retrieves the entire event history for ALL systems. Requires a system ID.
  • get_eventdetails.py: retrieves detailed information about one specific event in a system's history. Needs the system ID and the event ID.
  • get_eventhistory.py: retrieves a list of all events for one system over the last 30 days. Requires a system ID.
  • getresults_sm.py: this script will take a "jobs.csv" generated by runscripts_sm.py, query for all the results (including command output), and write them to a CSV.
  • list_activationkeys.py: returns a list of all activation keys present on the system
  • list_activesystems.py: returns a list of all ACTIVE systems (that have recently checked in with SUMA)
  • list_groups.py: returns a list of all defined system groups
  • list_systems.py: returns a list of all registered systems, including inactive ones
  • list_channels.py: returns a list of all defined software channels, including child ones
  • list_custominfo.py: returns all custominfo key/value pairs defined for a system. Requires a system ID.
  • list_cvestatus.py: asks SUMA to return the patch status for a named CVE on all registered systems. Statuses can be PATCHED, AFFECTED_PATCH_APPLICABLE or NOT_AFFECTED.
  • list_group_cves.py: unique open CVEs per system group, bucketed by CVSS score (Critical ≥9.0, High, Medium, Low, Unknown), with the number of systems exposed to critical CVEs and the highest CVSS per group. SUMA does not store CVSS, so scores come from SUSE's daily CVSS feed (https://ftp.suse.com/pub/projects/security/yaml/suse-cvss-scores.yaml, ~7 MB, downloaded on each run). For air-gapped servers, copy that file over and pass --cvss-file FILE. Uses the highest CVSS v3.x score per CVE, falling back to v4 and then v2. CVEs not in SUSE's feed (common for RHEL/Ubuntu-only CVEs) show as Unknown. Options: -g GROUP, --ungrouped, --details (list each group's CVEs), --min-cvss 9.0, --csv FILE (one row per group × CVE, with score, version, vector, affected systems and patches). SMLM's API has the CVE IDs for each patch but no CVSS scores, hence the external feed. The patch→CVE mapping (one errata.listCves call per patch, the slow part) is cached in ~/.cache/suma-patch-cves-<server>.json, so later runs only query new patches; --no-cache disables it and --workers N (default 4) sets how many calls run in parallel.
  • list_group_vulnerabilities.py: vulnerability report per system group. For each group, counts pending security patches by severity (Critical/Important/Moderate/Low), how many systems have critical patches pending, and the average System Currency score. Options: -g GROUP (repeatable) to filter groups, --ungrouped, --only-critical (list only systems with critical patches), --summary-only (hide the per-group system listing, shown by default), and --csv FILE for spreadsheet/Grafana import.
    • About the Score column: it is SUSE Manager's System Currency score (system.getSystemCurrencyScores), a weighted sum of all pending patches on the system. Higher means further behind; 0 means fully patched. Default weights: Critical 32, Important 16, Moderate 8, Low 4, Bugfix 2, Enhancement 1 (e.g. 3 crit + 164 imp + 59 mod + 8 low + 71 bug + 1 enh = 96 + 2624 + 472 + 32 + 142 + 1 = 3367). The weights can be changed in /etc/rhn/rhn.conf (java.sc_crit, java.sc_imp, java.sc_mod, java.sc_low, java.sc_bug, java.sc_enh), so scores may differ between servers. Because bugfixes count and Important patches tend to dominate, it is a "how outdated" metric, not a security-risk one: for criticality, use the Critical and w/Crit columns.
  • list_locked.py: returns a list of systems marked as "locked"
  • list_needsreboot.py: returns a list of systems that currently need rebooting.
  • list_config_channels.py: lists all configuration channels
  • list_inactive_systems.py: lists systems that have been inactive for X days.
  • list_orgs.py: lists all defined organizations
  • list_users.py: lists all defined users
  • lookup_systemid.py: looks up a hostname and returns the corresponding registered System ID.
  • migrate_system.py: does a complete system migration from one service pack to the other (interactive)
  • packagesinstalled90days.py: returns a list of all package actions that happened over the last 90 days, with status.
  • rebootsystem.py: schedules a reboot for a system.
  • runscript_sm.py: takes a list of hosts and a bash script, and schedules actions for every one of them. Use getresults_sm.py to fetch the results.
  • updateallpackages.py: installs all pending updates for a system
  • update_custominfo.py: sets a custominfo key/value pair for a specific system.

The migrate_system.py was inspired by the pull request at uyuni-project/uyuni-docs#3033, but I made it more interactive, with no hardcoded values.

  • schedule_highstate.py: schedules a hightstate event for a system
  • search_packages.py: search for packages in a specific channel
  • search_patches.py: search for patches in the database
  • system_details.py: fetch details for a specific system

curl scripts

By demand, I'm posting the curl-equivalent scripts. Note that you need the header.txt file present in the same directory, as they're reading from this file. I'm using the curl "cookie jar" feature to store/read the cookies/session ID tokens. You'll see a "cookies.txt" file being created after running any of these. The authentication token is removed at the end after the logout operation is performed on each script.

  • curl_getSystemCurrencyScores.sh: does the same as list_allsystems.py script, which is to list all available systems, but with the corresponding patches/bugfixes counts/scores.
  • curl_getId.sh: looks up a hostname and returns the corresponding System ID.
  • curl_listsystems.sh: returns basic data from all available systems (name, id, last checkin, etc)

Grafana dashboard

  • grafana/suse-manager-general-reports.json: source of the SUSE Manager General Reports dashboard. Unlike the scripts, it doesn't use the API: it reads SUSE Multi-Linux Manager's reporting database (reportdb) through a Grafana PostgreSQL data source, chosen at import time. It covers package/action activity, scheduled action progress, inventory, and a "Security by System Group" row (pending security patches per group by severity, patch age, oldest first), the dashboard counterpart of list_group_vulnerabilities.py. The reporting database is refreshed by Taskomatic (daily by default), so the data can be up to a day old; the "Reporting DB synced" tile shows when it was last refreshed.

See grafana/README.md for screenshots, how to configure Grafana to read the reporting database, and how to test it locally.