Initialize a trestle working directory.

This tool initializes the current directory as a Trestle workspace, creating the necessary directory structure for OSCAL model management.

OSCAL Model Types supported:

• Catalog

• Profile

• Component Definition

• System Security Plan (SSP)

• Assessment Plan

• Assessment Result

• Plan of Action and Milestones (POAM)

Args: params (TrestleInitInput): Validated input parameters containing: - mode (InitMode): Initialization mode (local/full/govdocs, default: local) - trestle_root (Optional[str]): Path to trestle root directory - verbose (bool): Display verbose output (default: false)

Returns: str: Success message or error details

Examples: - Use when: "Initialize trestle workspace" - Use when: "Set up trestle in full mode" - Don't use when: Workspace is already initialized

Import an existing OSCAL model into the trestle workspace.

This tool imports OSCAL models from URLs or local file paths. The imported file will be saved in the appropriate directory based on its OSCAL type (e.g., catalogs/, profiles/, component-definitions/).

Import Behavior:

• Catalog → catalogs/{output}/catalog.json

• Profile → profiles/{output}/profile.json

• Component Definition → component-definitions/{output}/component-definition.json

• SSP → system-security-plans/{output}/system-security-plan.json

Args: params (TrestleImportInput): Validated input parameters containing: - file (str): OSCAL file to import (URL or file path) - output (str): Name of output element - regenerate (bool): Force generation of new UUIDs (default: false) - trestle_root (Optional[str]): Path to trestle root directory - verbose (bool): Display verbose output (default: false)

Returns: str: Success message with import details or error

Examples: - Import NIST SP800-53 Rev5 Catalog: file="https://raw.githubusercontent.com/usnistgov/oscal-content/refs/heads/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json" output="nist_sp800_53_rev5"

- Import from local file:
  file="./resources/catalogs/your_catalog.json"
  output="mycatalog"

Generate Catalog controls in markdown form from a catalog in the trestle workspace.

Args: params (TrestleCatalogGenerateInput): Input parameters with: - name (str): Catalog model name (required) - output (str): Output markdown folder (required) - force_overwrite (bool): Force overwrite markdowns (optional) - yaml_header (Optional[str]): Path to yaml header file (optional) - overwrite_header_values (bool): Overwrite markdown header values (optional) - trestle_root (Optional[str]): Trestle workspace root path (optional) - verbose (bool): Display verbose output (optional)

Returns: str: Success or error message

Examples: - Use when: "Generate markdown controls from a catalog" - Use when: "Split a catalog JSON into control-wise markdowns" - Don't use when: "Catalog is missing or output directory already exists and not overwritten"

Generate markdown documentation set for controls defined in specified profile.

This tool extracts controls defined in the specified profile (profiles//profile.json) and generates a set of markdown documents for them. This set can be used for custom documentation, reviews, and organization-specific profile documentation.

Args: params (TrestleAuthorProfileGenerateInput): - name (str): profile name (required) - output (str): output directory for markdown docs (required) - yaml_header (Optional[str]): yaml header file path - force_overwrite (bool): overwrite all in output dir - overwrite_header_values (bool): overwrite header values only - sections (Optional[str]): targeted sections in markdown - required_sections (Optional[str]): required section short names, comma-separated - trestle_root (Optional[str]): workspace root path - verbose (bool): verbose output

Returns: str: Success message or error details

Examples: - Use when: "Generate markdown controls for a given profile" - Use when: "Customize output with required sections or header overwrite" - Don't use when: Profile file does not exist

Resolve an OSCAL profile to a resolved profile catalog.

This tool resolves a specified OSCAL profile (by name from profiles//profile.json) into an operational, parameter-resolved OSCAL catalog, with flexible output and formatting options.

Args: params (TrestleAuthorProfileResolveInput): - name (str): Source profile name (required) - output (str): Output catalog name (required) - show_values (bool): Show parameter values in prose (optional) - show_labels (bool): Show parameter labels in prose (optional) - bracket_format (str): Bracket format for values (optional) - value_assigned_prefix (str): Prefix if value is assigned (optional) - value_not_assigned_prefix (str): Prefix if value not assigned (optional) - label_prefix (str): Prefix for label output (optional) - verbose (bool): Display verbose output (optional) - trestle_root (str): Path to trestle root directory (optional)

Returns: str: Result summary string. On success, a checked message with output. On failure, a cross mark and error details.

Examples: - Minimal invocation trestle_author_profile_resolve(name="myprofile", output="catalog_resolved") - With options trestle_author_profile_resolve(name="myprofile", output="catalog_resolved", show_values=True, bracket_format="(.)")

Assemble markdown controls into a Profile JSON file.

This tool assembles an OSCAL profile JSON (profile.json) from a directory of markdown controls for a profile.

Args: params (TrestleAuthorProfileAssembleInput): - markdown_dir (str): Markdown controls directory (required) - output_profile (str): Output profile directory name (required) - name (Optional[str]): Profile model name - set_parameters (bool): Expand parameters from YAML frontmatter - regenerate (bool): Force UUID regeneration - version (Optional[str]): Model version - sections (Optional[str]): Section info (short:long, comma-separated) - required_sections (Optional[str]): Required section short names, comma-separated - allowed_sections (Optional[str]): Allowed section short names, comma-separated - verbose (bool): Verbose output - trestle_root (Optional[str]): Path of trestle root directory

Returns: str: Success message with stdout, or error message with stderr details

Examples: - Use when: Automatically assemble OSCAL profile from markdown directory - Use when: CI/CD profile assembling, parameter expansion - Don't use when: Input markdown_dir does not exist, or malformed markdown

Convert a CSV file to an OSCAL component definition JSON file.

This tool runs the trestle task csv-to-oscal-cd command, which reads a specially formatted CSV file and produces an OSCAL component_definition .json file.

The CSV must have:

• Row 1: column headings

• Row 2: column descriptions

• Row 3+: data rows

Required CSV columns:

• $$Component_Title, $$Component_Description, $$Component_Type

• $$Rule_Id, $$Rule_Description, $$Profile_Source, $$Profile_Description

• $$Control_Id_List, $$Namespace

Args: params (TrestleTaskCsvToOscalCdInput): Input parameters with: - title (str): Component definition title (required) - version (str): Component definition version (required) - csv_file (str): Path to the input CSV file (required) - output_dir (str): Output directory for OSCAL JSON files (required) - component_definition (Optional[str]): Existing component-definition to update (optional) - output_overwrite (bool): Overwrite existing output (default: true) - validate_controls (str): Control validation mode: on/warn/off (default: off) - class_column_mappings (Optional[dict]): Column-to-class mappings (optional) - trestle_root (Optional[str]): Trestle workspace root path (optional) - verbose (bool): Display verbose output (optional)

Returns: str: Success or error message with output file location

Examples: - Use when: "Convert CSV to OSCAL component definition" - Use when: "Generate component_definition.json from a CSV mapping file" - Don't use when: Input CSV is missing required columns

Convert a FedRAMP XLSX spreadsheet to an OSCAL POA&M JSON file.

This tool runs the trestle task xlsx-to-oscal-poam command, which reads a FedRAMP-format .xlsx spreadsheet and produces an OSCAL plan-of-action-and-milestones .json file. The converter auto-generates the observations[] and risks[] and cross-links each poam-item to them with deterministic UUIDs.

This command must run inside a trestle workspace: initialize one first with trestle_init and pass its path as trestle_root (or run from within it).

The spreadsheet must have:

• Row 1: title

• Rows 2-4: instructions (ignored)

• Row 5: column headers

• Row 6+: data rows

Required columns:

• POAM ID, Weakness Name, Weakness Description, Controls

Args: params (TrestleTaskXlsxToOscalPoamInput): Input parameters with: - title (str): POA&M title (required) - version (str): POA&M version (required) - xlsx_file (str): Path to the input .xlsx file (required) - output_dir (str): Output directory for the OSCAL JSON (required) - work_sheet_name (Optional[str]): Worksheet name (default: 'Open POA&M Items') - system_id (Optional[str]): System identifier (optional) - output_overwrite (bool): Overwrite existing output (default: true) - validate_required_fields (str): Required-field check: on/warn/off (default: warn) - quiet (bool): Suppress per-item output (default: false) - trestle_root (Optional[str]): Trestle workspace root path (optional) - verbose (bool): Display verbose output (optional)

Returns: str: Success or error message with output file location

Examples: - Use when: "Convert this FedRAMP POA&M spreadsheet to OSCAL" - Use when: "Generate plan-of-action-and-milestones.json from an xlsx" - Don't use when: The input is a CSV, or is missing required columns

Validate a standalone OSCAL file against the OSCAL schema.

This tool loads the OSCAL document through the trestle model classes, which enforces the OSCAL schema (required fields, field types, enums, UUID formats, and nesting). Optionally it also runs trestle's semantic validators (duplicate UUIDs, broken internal references, links, and rule parameters).

It detects the model type from the file's single top-level wrapper key, so it validates any top-level OSCAL model: catalog, profile, component-definition, system-security-plan, assessment-plan, assessment-results, or plan-of-action-and-milestones.

Unlike trestle validate on the CLI, this works on a standalone file that is not part of a trestle workspace — for example a POA&M JSON produced by an authoring flow.

Args: params (TrestleValidateInput): Input parameters with: - file (str): Path to the OSCAL .json/.yaml/.yml file (required) - expected_model_type (Optional[str]): Enforce the file is this model type (e.g. 'plan-of-action-and-milestones') - semantic (bool): Run semantic validators too (default: true)

Returns: str: A pass/fail message; on failure, the concrete reasons.

Examples: - Use when: "Validate this POA&M JSON is valid OSCAL" file="./poam.json", expected_model_type="plan-of-action-and-milestones" - Use when: "Check that catalog.json conforms to the OSCAL schema" - Don't use when: The file is inside a trestle workspace and you want the full trestle validate workspace checks.