.. _data-and-permissions: STIG Manager API Data Representations and Permissions ########################################################################## Data Model ==================================================== STIG Manager's primary organizational structure is the Collection. A Collection can be created to mirror components of an RMF Package, requirements identified in a Security Assessment Plan, or an entirely different principle that may be more convenient, such as by an organization's Lab or by Asset OS. Collections are composed of: * Assets * STIGs attached to those Assets * Reviews of the Rules that compose each attached STIG * Grants to Users or Groups providing access to some or all of the Assets/STIGs in that Collection * Metrics providing Status and Findings counts for each Asset and STIG in the Collection Metadata --------------------------------------------- Collections, Assets, and Reviews all support a JSON field called "metadata" for general use that can be used to enhance functionality and associate arbitrary data with those elements. The project is exploring best practices and uses for this feature. Third-party Clients that "play nice" with this field would be expected to preserve metadata already there unless they put it there, perhaps in a nested object with their client name as the Key. The Project Clients and API make use of the following metadata keys. These keys are reserved for use by the STIG Manager project and should not be used by third-party Clients: * Collection Metadata: - ``importOptions`` - Guidance for clients to follow when posting reviews for this collection that are NOT enforced by the API. See :ref:`import-options` for more information. * Asset Metadata - ``cklWebOrDatabase`` - A boolean indicating whether the Asset is a Web or Database server. See :ref:`ckl-processing` - ``cklHostName`` - The hostname of the Asset as it appears in a .ckl file. See :ref:`ckl-processing` - ``cklWebDbSite`` - The Web or Database Site of the Asset as it appears in a .ckl file. See :ref:`ckl-processing` - ``cklWebDbInstance`` - The Web or Database Instance of the Asset as it appears in a .ckl file. See :ref:`ckl-processing` * Review Metadata - ``artifacts`` - Array of objects describing the artifacts attached to the review. Each item includes name, type, size, description, user, timestamp, and digest of the artifact content. - ```` - Base64-encoded content of the artifact. .. note:: This usage of Review metadata for artifacts is experimental and subject to change or deprecation. Reference STIGs --------------------------------------------- STIG Manager uses a set of Reference STIGs that it makes available for assignment to Assets, tracks Rule evaluation, and against which it calculates all metrics. These Reference STIGs must be imported and updated periodically as new STIGs are released or updates are made. It is responsibility of a User with the "Application Management" (ie. "admin") privilege to import these official STIGs and keep them updated. Usually, these STIGs are released by DISA on a quarterly schedule. Wherever the content of a STIG is displayed (STIG Rules, Rule Titles, Rule Descriptions, Fix Texts, Severities, etc.) this data is drawn from the Reference STIG imported by the Application Manager. It is important to note the distinction here between STIG content and "Review" content, which is usually drawn from imported .ckl files or manual results inputted into STIG Manager by Reviewers. This "Review" content only affects the "Review" or "Evaluation" portion of the data displayed in STIG Manager. They cannot change Reference STIG content via .ckl imports. "Checklists" - .ckl/b and XCCDF --------------------------------------------- Assets and the STIGs assigned to them are generally presented as Checklists, the lists of Rules and Checks that compose the assigned STIG, and the Reviews that satisfy those Rules. STIG Manager associates Reviews with specific content of Rules (Rule Version and Rule Check Content), independent of the STIGs that are assigned to Assets. This allows for different and more useful presentations of the data than when the Reviews are expressed in flat files, such as .ckl or XCCDF files. It is important to note that STIG Manager does not retain the actual .ckl or XCCDF files that are imported into it in any way. The files are parsed for the information they contain, and that information is stored in the database. Manual edits via the UI and new imports all contribute to the current state of an Asset's reviews as presented by the UI and API. NEW .ckl/b or XCCDF files are generated on demand reflecting the current state of a Collections Assets, STIGs, and reviews. This approach provides several advantages: - Reviews are associated with the specific content of a Rule (Rule Version and Rule Check Content). - Review attribution info, status, and metadata can be attached to each individual Review. - Checklists are generated using the **Reference** STIGs imported and maintained by the Application Manager. This alleviates issues with partial checklists, unauthorized overrides, etc. .. _ckl-processing: Processing .ckl Files ________________________ When the STIG Manager Client imports data from :term:`.ckl files `, in the simplest case it will attempt to match (and, in some instances, create) the Asset specified in the .ckl's ```` element. However, if the ```` element in the .ckl has a value of ``true``, special processing is invoked. This processing will attempt to match the ````, ```` and ```` values in the .ckl with Asset metadata when identifying the Asset. When the STIG Manager Client creates Assets from .ckls with these elements populated, it will populate the same Asset metadata according to the table below. Conversely, when STIG Manager produces a .ckl file from an Asset that has the below metadata values set, it will populate the appropriate .ckl elements. The following metadata properties are used when the value of ```` is ``true``: .. list-table:: **CKL elements map to STIG Manager Asset metadata** :widths: 20 20 60 :header-rows: 1 :class: tight-table * - ```` Child Element - Asset metadata - Note * - ```` - ``cklWebOrDatabase`` - When set to true, invokes additional processing using the below elements and metadata * - ```` - ``cklHostName`` - This value will populate the ```` element of a ckl, as opposed to the Asset name in other cases. * - ```` - ``cklWebDbSite`` - No specific purpose for STIG Manager, other than contributing to Asset identification * - ```` - ``cklWebDbInstance`` - No specific purpose for STIG Manager, other than contributing to Asset identification If the importer needs to create an Asset, it will set this metadata and set the initial Asset name to ``-[ | "NA"]-[ | "NA"]``. The Asset name is not meaningful (to STIG Manager) and it can be changed by the user later, if required. .. thumbnail:: /assets/images/asset-metadata-and-ckl-elements.png :width: 75% :show_caption: True :title: Corresponding Asset Metadata and .ckl elements | .. note:: See the :ref:`import-options` section of this document for information about STIG Manager's review import options. | Processing XCCDF Files __________________________________ STIG Manager supports serializing Reviews in XCCDF format with a STIG Manager namespace (``xmlns:sm="http://github.com/nuwcdivnpt/stig-manager"``). Correct serialization was validated using `the official NIST validation tool `_. The XCCDF format is more expressive and extensible than the .ckl format, so additional data can be included. Not all tools will recognize elements making use of the STIG Manager namespace, but the files will still validate and test result information will be recognized. STIG Manager itself can re-import it's own XCCDF files and will understand the STIGMan namespace fields. STIGMan serializes elements containing data that are STIGMan specific, as well as other elements required to express test results and stay in accordance with the NIST XCCDF specification: - A STIGMan XCCDF file contains these elements and features: - ```` - ```` and required children - ```` and required children - Identifies STIG Manager as the test system ``cpe:/a:nuwcdivnpt:stig-manager:[version]`` - Serializes STIG Manager Asset properties and metadata as children of ```` - Asset properties are described by ````. Each child element is scoped to the STIG Manager namespace. The following elements are used: - ``sm:detail`` - ``sm:comment`` - ``sm:resultEngine`` - ``sm:type`` - ``sm:product`` - ``sm:version`` - ``sm:time`` - ``sm:checkContent`` - ``sm:location`` - ``sm:component`` - ``sm:overrides`` - ``sm:authority`` - ``sm:oldResult`` - ``sm:newResult`` - ``sm:remark`` Application Access ============================= API Endpoints, Scopes, and Privilege Invocation ------------------------------------------------------------------------ Overall access to the STIG Manager application is controlled by the OIDC provider. STIG Manager recognizes two "privileges" that can be granted to users via configuration in the OIDC provider. Users with the **create_collection** privilege can create new Collections of their own, but are otherwise ordinary users. Users with the **admin** privilege may explicitly invoke the ``elevate`` parameter in API requests to act as a privileged principal. The elevation mechanism is designed so that an admin user does not need a separate privileged account on the identity provider — the same account is used, and the user opts into elevated mode on a per-request basis. When a request includes ``?elevate=true``, it is governed by the elevation access model rather than by any Collection Grant the user may also hold. Elevation is scoped exclusively to Collection management and application administration operations: - Enumerate, create, and delete Collections - Read and modify a Collection's name and description - Create, modify, and delete Grants on any Collection, assigning any Role to any User or User Group (without supplying an ACL) - Manage Users and User Groups Elevation does **not** grant access to collection content. An elevated admin cannot read or write Reviews, access Asset or STIG checklist data, or modify a Collection's settings, labels, metadata, or Grant ACLs — even with ``?elevate=true`` supplied. These operations require a Collection Grant and are performed via normal (non-elevated) requests. In the reference UI, the ``elevate`` parameter is sent when "Application Management" functions are invoked, such as importing new Reference STIGs, listing all Collections, or creating a Grant in a Collection the admin does not otherwise have access to. .. note:: An elevated admin can create a Grant giving themselves any Role in any Collection. This is intentional: it avoids requiring admins who also need content access to maintain a second OIDC account. The accepted control is that **every elevated request — including self-grant operations — has its complete request and response bodies written to the application log**, regardless of whether the request succeeds. Administrators responsible for deploying STIG Manager should ensure elevated-request log entries are retained and reviewed. These **privileges** must be present in the token presented to the API in order to be successfully invoked. Access to specific endpoints is controlled by the **scopes** present in a user's token. The scopes granted to users can be configured in the OIDC provider. Certain user types may only need access to certain scopes. For example, an "Application Manager" type user might need access to the ``stig-manager:stig`` scope so that they can update the Reference STIGs in the app, but normal users might only need the ``stig-manager:stig:read`` scope, granting them read-only access to the Reference STIGs. All configuration of this type is done in the OIDC provider. See our :ref:`Authentication and Identity ` documentation and our `API Specification `_ for more information about how these scopes and privileges interrelate. .. note:: An authorized user will not have access to Collection data until they have been assigned a Grant to one by a Collection Owner or Manager, or create a Collection themselves. See :ref:`roles-and-access` for more information about how Grants are managed. Database Entity Relationship Diagrams =============================================== The following diagram may not always be up to date. Always refer to the implemented db structure as the authoritative source for this information. .. thumbnail:: /assets/images/eer-stigman.png :width: 75% :show_caption: True :title: Entity Relationship Diagram representation of STIG Manager's MySQL data. `View the enlarged ERD Document here. <../_images/eer-stigman1.png>`_