Using Python API

[Yesser-Belhajali]

Hello everyone,
I'm building a project on top of OpenSCAP and was considering using the Python bindings (python3-openscap / openscap_api.py) instead of shelling out to the oscap CLI, since callbacks (register_start_callback / register_output_callback) looked like a cleaner way to get structured, per-rule results.

I also noticed the last commit touching the swig/ folder is about 3 years old, with very little recent activity or documentation/examples for modern use cases (SDS handling, tailoring, etc.).
So my actual question: is this Python binding still a reliable, maintained option for a new project today, or has it effectively been left behind in favor of the CLI? Specifically:

Does anyone have a working, modern example of loading a full Source Data Stream (selecting datastream-id + xccdf-id) through this binding?
Is there a recommended replacement (Ruby binding? Direct C API? CLI-only?) for new projects that need programmatic access rather than parsing CLI output?
Is this binding still considered supported by the OpenSCAP team, or is it legacy/best-effort only?

[yhay81]

The bindings are not completely abandoned, but I would not choose the high-level openscap_api.py wrapper as the primary interface for a new SDS-based application.

There are two different maintenance stories in the tree:

• The SWIG bindings are still a build feature (ENABLE_PYTHON3 defaults on when Python/SWIG are present), have binding tests, and even received a compiler-compatibility fix in January 2024. So they are not formally removed/deprecated.
• The hand-written high-level openscap_api.py is much less complete. Its DS_Class is empty and xccdf.init() imports a standalone benchmark plus referenced OVAL files; it does not implement the modern SDS/session selection workflow. The callback helpers you found belong to that older policy-model path.

The current SDS-capable API is the C xccdf_session interface: xccdf_session_new(), set_datastream_id(), set_component_id() (the CLI calls this --xccdf-id), set_profile_id(), set_user_tailoring_file(), load(), evaluate(), and get_rule_results(). SWIG may expose those low-level symbols, but using them through the dynamic OSCAP_Object wrapper means you are effectively programming against the C API with Python ownership/callback hazards and little documentation—not a stable Pythonic SDK.

For a production Python service, my recommendation is therefore:

subprocess.run([
    "oscap", "xccdf", "eval",
    "--datastream-id", datastream_id,
    "--xccdf-id", xccdf_id,
    "--profile", profile_id,
    "--tailoring-file", tailoring_file,
    "--results", results_xml,
    "--results-arf", results_arf,
    sds_path,
], check=False)

Parse results_xml/ARF for structured per-rule results rather than stdout. That preserves the fully exercised CLI loading/selection/tailoring path and gives you standardized XCCDF result data. Capture stdout/stderr only for diagnostics.

If in-process callbacks are a hard requirement, use the public C xccdf_session API directly (or write a small, purpose-built extension around it) and follow utils/oscap-xccdf.c as the reference implementation. The Ruby/Perl-style bindings are not a more modern replacement; they are also generated bindings over the same C surface.

So the practical answer is: bindings still build and receive compatibility fixes, but the high-level Python wrapper is legacy/best-effort for modern SDS workflows; CLI + result XML is the safest supported integration for a new Python project, and direct C is the path when callbacks/in-process control justify the extra complexity.

[Yesser-Belhajali]

Thank you very much for your previous answer. It helped me a lot and clarified many concepts.

I decided to work directly with the C API because it gives me more control over the scanning process. To better understand the library, I started studying the header files, the exposed functions, and the internal structures. I also went a bit deeper into the implementation to understand how memory is managed and how everything is organized internally so I can optimize my application as much as possible. Since I am still relatively new to C, I would really appreciate some additional guidance.

From what I have understood so far, the high-level API revolves around struct xccdf_session (defined in xccdf_session.c). I understand that this structure acts as a container for different components of the scanning process (XCCDF, OVAL, etc.), but I wanted to go further and understand how rules are represented and evaluated internally.

While studying the members of struct xccdf_session, I noticed that it contains a policy_model member. Looking further into that, I found that struct xccdf_policy_model contains a benchmark member. This is where I started getting confused.

I am having difficulty understanding the conceptual and implementation differences between the following objects:

• xccdf_benchmark
  -xccdf_policy_model
  -xccdf_policy

Initially, I assumed that a policy was simply a profile, but after reading more of the code, I no longer think that is correct.

Another point that confused me is the implementation of xccdf_benchmark. I searched through the project but could not find the actual definition of struct xccdf_benchmark. However, I found struct xccdf_item, and I noticed that the benchmark constructor internally creates an xccdf_item. This made me wonder whether OpenSCAP is using xccdf_item as a base structure and whether this is the common C technique for implementing something similar to object-oriented inheritance by embedding one structure inside another.

Finally, I would like to make sure I understand the XCCDF object model correctly.

My current understanding is:

• An XCCDF file contains rules, profiles, values, groups, benchmarks, and other related elements.
• A benchmark represents the complete security content (rules, profiles, values, groups, etc.).
• A profile selects or tailors a subset of that benchmark.

However, I am not confident that this understanding is correct, especially regarding the relationship between:

• XCCDF
• Benchmark
• Policy Model
• Policy
• Profile

Could you explain the role of each of these concepts,how they relate to one another conceptually, and how they are represented internally in libopenscap? A high-level explanation together with how these objects map to the library's internal structures would be extremely helpful.