diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..c5f3f6b9 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "java.configuration.updateBuildConfiguration": "interactive" +} \ No newline at end of file diff --git a/README.md b/README.md index d60b1b9e..644679f1 100644 --- a/README.md +++ b/README.md @@ -102,9 +102,40 @@ To disable colored output, use the `--no-color` flag: oscal-cli --no-color ``` +### Shell Completion + +The CLI supports tab completion for Bash and Zsh shells, providing intelligent suggestions for commands, subcommands, and options. + +**Bash:** + +```bash +# Generate and source completion (temporary, current session only) +source <(oscal-cli shell-completion bash) + +# Or save to a file and source it in your ~/.bashrc for persistence +oscal-cli shell-completion bash > ~/.oscal-completion.bash +echo 'source ~/.oscal-completion.bash' >> ~/.bashrc +``` + +**Zsh:** + +```zsh +# Ensure your completions directory exists +mkdir -p ~/.zsh/completions + +# Generate completion script +oscal-cli shell-completion zsh > ~/.zsh/completions/_oscal-cli + +# Add to your ~/.zshrc if not already configured +echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc +echo 'autoload -Uz compinit && compinit' >> ~/.zshrc +``` + +After setting up completion, restart your shell or source the configuration file. + ## Building -This project can be built with [Apache Maven](https://maven.apache.org/) version 3.8.4 or greater. +This project can be built with [Apache Maven](https://maven.apache.org/) version 3.9.0 or greater. The following instructions can be used to clone and build this project. diff --git a/src/site/markdown/building.md.vm b/src/site/markdown/building.md.vm new file mode 100644 index 00000000..127564aa --- /dev/null +++ b/src/site/markdown/building.md.vm @@ -0,0 +1,195 @@ +# Building from Source + +This guide explains how to build the OSCAL CLI from source code. + +## Prerequisites + +| Requirement | Minimum Version | Notes | +|:------------|:----------------|:------| +| Java JDK | 17 | Required for building (output JARs are JDK 11 compatible) | +| Maven | 3.9.0 | Required for building | +| Git | 2.0 | Required for cloning | + +Ensure `JAVA_HOME` is set correctly: + +```bash +# macOS +export JAVA_HOME=$(/usr/libexec/java_home -v 17) + +# Linux (adjust path to your installation) +export JAVA_HOME=/usr/lib/jvm/java-17-openjdk + +# Windows +set JAVA_HOME=C:\Program Files\Java\jdk-17 +``` + +## Clone the Repository + +Clone the repository with submodules: + +```bash +git clone --recurse-submodules https://github.com/metaschema-framework/oscal-cli.git +cd oscal-cli +``` + +If you already cloned without submodules, initialize them: + +```bash +git submodule update --init --recursive +``` + +## Build Commands + +### Basic Build + +Build and install to your local Maven repository: + +```bash +mvn install +``` + +This produces the CLI distribution in `target/oscal-cli-enhanced-*-oscal-cli.zip`. + +### Run Tests Only + +```bash +mvn test +``` + +### Run a Single Test + +```bash +# Run a single test class +mvn test -Dtest=CLITest + +# Run a single test method +mvn test -Dtest=CLITest#testValidate +``` + +### Skip Tests + +```bash +mvn install -DskipTests +``` + +### CI/CD Build + +Replicate the full CI/CD build (recommended before pushing): + +```bash +mvn install -PCI -Prelease +``` + +This enables additional checks including: + +- License header verification +- Checkstyle code style checks +- SpotBugs static analysis +- Full test suite + +## Code Quality Commands + +### Check License Headers + +```bash +mvn license:check +``` + +### Auto-format Source Code + +```bash +mvn formatter:format +``` + +### Check for Checkstyle Issues + +```bash +mvn checkstyle:check +``` + +## Running the Built CLI + +After building, you can run the CLI directly: + +```bash +# Extract the distribution +unzip target/oscal-cli-enhanced-*-oscal-cli.zip -d target/cli + +# Run the CLI +target/cli/bin/oscal-cli --help +``` + +## Building Container Images + +To build a local container image: + +```bash +# Build with Docker +docker build -t oscal-cli:local . + +# Test the image +docker run --rm oscal-cli:local --help +``` + +## Building the Site + +To build the project documentation site: + +```bash +mvn site +``` + +The generated site appears in `target/site/`. + +## Common Build Issues + +### Submodule Not Initialized + +**Symptom:** Build fails with missing OSCAL or Metaschema files. + +**Solution:** Initialize submodules: + +```bash +git submodule update --init --recursive +``` + +### Java Version Mismatch + +**Symptom:** Compilation errors or "unsupported class file version" errors. + +**Solution:** Ensure you're using Java 17 or later for building: + +```bash +java -version +mvn -version +``` + +### Maven Version Too Old + +**Symptom:** Build fails with plugin compatibility errors or enforcer rule failures. + +**Solution:** Upgrade Maven to 3.9.0 or later: + +```bash +mvn -version +``` + +### Out of Memory + +**Symptom:** Build fails with `OutOfMemoryError`. + +**Solution:** Increase Maven's heap size: + +```bash +export MAVEN_OPTS="-Xmx2g" +mvn install +``` + +## Contributing + +For contribution guidelines, including code style requirements and the pull request process, see [CONTRIBUTING.md](${project.scm.url}/blob/develop/CONTRIBUTING.md). + +## Next Steps + +- [Installation](installation.html) - Install the pre-built CLI +- [CLI Reference](guides/cli-reference.html) - Complete command reference diff --git a/src/site/markdown/claude-integration.md.vm b/src/site/markdown/claude-integration.md.vm new file mode 100644 index 00000000..972f6e5d --- /dev/null +++ b/src/site/markdown/claude-integration.md.vm @@ -0,0 +1,115 @@ +# Using with Claude Code + +[Claude Code](https://claude.ai/code) is an AI-powered coding assistant that can help you work with OSCAL CLI more effectively. + +## Overview + +Claude Code plugins provide specialized skills for: + +- **OSCAL document validation** - Validating catalogs, profiles, SSPs, and other OSCAL artifacts +- **Format conversion** - Converting between XML, JSON, and YAML formats +- **Profile resolution** - Resolving profiles to produce baseline catalogs +- **Metapath queries** - Writing expressions to query OSCAL content +- **CLI assistance** - Running commands and interpreting output + +## Prerequisites + +1. [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code) + +## Available Plugins + +### OSCAL Plugin + +Skills for working with OSCAL documents: + +| Skill | Description | +|:------|:------------| +| `oscal:oscal-basics` | OSCAL document types and structure | + +### OSCAL Tools Plugin + +Skills for using the CLI: + +| Skill | Description | +|:------|:------------| +| `oscal-tools:using-oscal-cli` | Running oscal-cli commands | + +### Metaschema Plugin + +Skills for understanding OSCAL's underlying structure: + +| Skill | Description | +|:------|:------------| +| `metaschema:metaschema-basics` | Introduction to Metaschema concepts | +| `metaschema:metapath-expressions` | Writing Metapath queries | + +## Example Workflows + +### Validate an OSCAL Document + +Ask Claude: +> "Validate my SSP at `ssp.json` and explain any errors" + +Claude will run the validation and help you understand and fix issues. + +### Convert Between Formats + +Ask Claude: +> "Convert my catalog from XML to JSON" + +Claude will guide you through the conversion process. + +### Resolve a Profile + +Ask Claude: +> "Help me resolve my NIST 800-53 profile to a baseline catalog" + +Claude will explain profile resolution and run the appropriate command. + +### Query OSCAL Content + +Ask Claude: +> "Write a Metapath expression to find all controls with a specific label" + +Claude will construct the expression and show how to use it with the CLI. + +### Debug Validation Errors + +Ask Claude: +> "I'm getting validation errors on my component definition. Can you help?" + +Claude will analyze the errors and suggest fixes. + +## Tips for Effective Use + +1. **Be specific** - Mention file paths and exact error messages +2. **Provide context** - Share the OSCAL document type you're working with +3. **Ask for explanations** - Claude can explain OSCAL concepts and requirements +4. **Request examples** - Ask for sample OSCAL snippets or CLI commands + +## Common Commands + +Here are CLI commands that Claude can help you with: + +```bash +# Validate OSCAL content +oscal-cli validate document.json + +# Convert formats +oscal-cli convert --to=json catalog.xml catalog.json + +# Resolve a profile +oscal-cli resolve-profile profile.xml resolved-catalog.xml + +# Evaluate Metapath expressions +oscal-cli metapath eval -e "//control" catalog.json +``` + +## Learn More + +For more information about Claude Code, OSCAL, and the CLI, see these resources: + +- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) +- [Metaschema Claude Plugins](https://github.com/metaschema-framework/claude-plugins/tree/main) - Source for the skills mentioned above +- [OSCAL Documentation](https://pages.nist.gov/OSCAL/) +- [CLI Reference](guides/cli-reference.html) diff --git a/src/site/markdown/guides/cli-reference.md.vm b/src/site/markdown/guides/cli-reference.md.vm new file mode 100644 index 00000000..c60d9ff5 --- /dev/null +++ b/src/site/markdown/guides/cli-reference.md.vm @@ -0,0 +1,284 @@ +# CLI Reference + +This page provides a complete reference for all oscal-cli commands and options. For task-oriented guides, see the individual guide pages linked at the bottom. + +## Global Options + +These options work with any command and control the general behavior of the CLI: + +| Option | Description | +|:-------|:------------| +| `--help`, `-h` | Show help for any command | +| `--version`, `-V` | Show version information | +| `--show-stack-trace` | Show detailed error information | +| `--quiet`, `-q` | Suppress non-essential output | + +## Commands + +### validate + +Validate OSCAL documents for well-formedness and schema compliance. + +```bash +oscal-cli validate [options] +``` + +**Arguments:** + +| Argument | Description | +|:---------|:------------| +| `` | Path or URL to OSCAL document | + +**Options:** + +| Option | Description | +|:-------|:------------| +| `--as=` | Force input format: `xml`, `json`, `yaml` | + +**Examples:** + +```bash +# Validate a JSON file +oscal-cli validate ssp.json + +# Validate with explicit format +oscal-cli validate --as=json document.txt + +# Validate remote file +oscal-cli validate https://example.com/catalog.json + +# Validate with detailed errors +oscal-cli validate --show-stack-trace ssp.json +``` + +**Exit Codes:** + +| Code | Meaning | +|:-----|:--------| +| 0 | Validation passed | +| 1 | Validation failed | +| 2 | Invalid arguments | + +--- + +### convert + +Convert OSCAL documents between XML, JSON, and YAML formats. + +```bash +oscal-cli convert [options] [destination] +``` + +**Arguments:** + +| Argument | Description | +|:---------|:------------| +| `` | Input file path or URL | +| `[destination]` | Output file path (optional, stdout if omitted) | + +**Options:** + +| Option | Description | +|:-------|:------------| +| `--to=` | Output format: `xml`, `json`, `yaml` (required) | +| `--as=` | Input format: `xml`, `json`, `yaml` | +| `--overwrite` | Overwrite existing output file | + +**Examples:** + +```bash +# Convert XML to JSON +oscal-cli convert --to=json catalog.xml catalog.json + +# Convert to stdout +oscal-cli convert --to=json catalog.xml + +# Convert with overwrite +oscal-cli convert --to=json --overwrite catalog.xml catalog.json +``` + +--- + +### resolve-profile + +Resolve an OSCAL profile to a catalog. + +```bash +oscal-cli resolve-profile [options] [catalog] +``` + +**Arguments:** + +| Argument | Description | +|:---------|:------------| +| `` | Input profile file or URL | +| `[catalog]` | Output catalog file (optional, stdout if omitted) | + +**Options:** + +| Option | Description | +|:-------|:------------| +| `--to=` | Output format: `xml`, `json`, `yaml` | +| `--as=` | Input format: `xml`, `json`, `yaml` | +| `--overwrite` | Overwrite existing output file | + +**Examples:** + +```bash +# Resolve profile to JSON catalog +oscal-cli resolve-profile profile.json resolved-catalog.json + +# Resolve with format conversion +oscal-cli resolve-profile --to=xml profile.json resolved-catalog.xml + +# Resolve to stdout +oscal-cli resolve-profile --to=json profile.xml +``` + +--- + +### metapath + +Work with Metapath expressions. + +#### metapath eval + +Evaluate a Metapath expression against a document. + +```bash +oscal-cli metapath eval [options] -e +``` + +**Arguments:** + +| Argument | Description | +|:---------|:------------| +| `` | Input file to query | + +**Options:** + +| Option | Description | +|:-------|:------------| +| `-e ` | Metapath expression to evaluate (required) | +| `--to=` | Output format: `xml`, `json`, `yaml` | + +**Examples:** + +```bash +# Query all controls +oscal-cli metapath eval -e "//control" catalog.json + +# Query with JSON output +oscal-cli metapath eval -e "//control/title" --to=json catalog.json + +# Count elements +oscal-cli metapath eval -e "count(//control)" catalog.json +``` + +--- + +### shell-completion + +Generate shell completion scripts. + +```bash +oscal-cli shell-completion +``` + +**Arguments:** + +| Argument | Description | +|:---------|:------------| +| `` | Shell type: `bash` or `zsh` | + +**Examples:** + +```bash +# Generate Bash completion +oscal-cli shell-completion bash > oscal-cli-completion.bash + +# Generate Zsh completion +oscal-cli shell-completion zsh > _oscal-cli +``` + +--- + +## OSCAL Document Types + +The CLI automatically detects the document type by examining the root element. You don't need to specify the document type—validation and conversion work for all types: + +| Type | Root Element | +|:-----|:-------------| +| Catalog | `catalog` | +| Profile | `profile` | +| Mapping Collection | `mapping-collection` | +| System Security Plan | `system-security-plan` | +| Component Definition | `component-definition` | +| Assessment Plan | `assessment-plan` | +| Assessment Results | `assessment-results` | +| POA&M | `plan-of-action-and-milestones` | + +## Format Detection + +The CLI determines input format from the file extension. This works for most cases: + +| Extension | Format | +|:----------|:-------| +| `.xml` | XML | +| `.json` | JSON | +| `.yaml`, `.yml` | YAML | + +Use `--as` to override detection for files with non-standard extensions. + +## Environment Variables + +The CLI respects standard Java environment variables for configuration: + +| Variable | Description | +|:---------|:------------| +| `JAVA_HOME` | Java installation directory | +| `JAVA_OPTS` | JVM options (e.g., `-Xmx2g`) | + +## Container Reference + +When using Docker, the following tags and options are available: + +### Image Tags + +| Tag | Description | +|:----|:------------| +| `latest` | Latest stable release | +| `x.y.z` | Specific version | +| `develop` | Latest development build | + +### Volume Mounting + +Mount local directories to make your files accessible inside the container: + +```bash +# Mount current directory +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest ... + +# Mount specific directory +docker run --rm -v "/path/to/files:/data" ghcr.io/metaschema-framework/oscal-cli:latest ... +``` + +### Resource Limits + +For large documents, you may need to increase container memory or CPU limits: + +```bash +# Limit memory +docker run --rm -m 2g ghcr.io/metaschema-framework/oscal-cli:latest ... + +# Limit CPU +docker run --rm --cpus 2 ghcr.io/metaschema-framework/oscal-cli:latest ... +``` + +## See Also + +- [Installation](../installation.html) - Install the CLI +- [Validating OSCAL](validating-oscal.html) - Validation guide +- [Converting Formats](converting-formats.html) - Conversion guide +- [Resolving Profiles](resolving-profiles.html) - Profile resolution guide +- [Working with Metaschema](working-with-metaschema.html) - Metapath queries diff --git a/src/site/markdown/guides/converting-formats.md.vm b/src/site/markdown/guides/converting-formats.md.vm new file mode 100644 index 00000000..af7890ed --- /dev/null +++ b/src/site/markdown/guides/converting-formats.md.vm @@ -0,0 +1,252 @@ +# Converting Formats + +This guide explains how to convert OSCAL documents between XML, JSON, and YAML formats. + +## Why Convert? + +OSCAL supports three serialization formats—XML, JSON, and YAML—with identical semantics across all three. Organizations often need to convert between formats for various reasons: + +- **Tooling requirements** - Different tools in your workflow may require specific formats +- **Standardization** - Establishing a single canonical format for your organization +- **Human readability** - YAML is often preferred for manual editing, XML for transformation +- **Integration** - APIs and web services typically prefer JSON +- **Storage efficiency** - JSON is generally more compact than XML + +The OSCAL CLI makes conversion simple. Because OSCAL defines format-agnostic semantics, you can convert documents without data loss—the information remains identical regardless of format. + +## Overview + +The `convert` command transforms OSCAL documents between supported formats while preserving all content and structure. The command reads the input document, validates it against the OSCAL model, and writes it in the target format. + +## Basic Conversion + +### XML to JSON + +```bash +oscal-cli convert --to=json catalog.xml catalog.json +``` + +### JSON to XML + +```bash +oscal-cli convert --to=xml ssp.json ssp.xml +``` + +### JSON to YAML + +```bash +oscal-cli convert --to=yaml profile.json profile.yaml +``` + +### YAML to JSON + +```bash +oscal-cli convert --to=json component.yaml component.json +``` + +## Format Detection + +The CLI determines the input format automatically by examining the file extension. This makes typical conversions simple—you only need to specify the desired output format: + +| Extension | Format | +|:----------|:-------| +| `.xml` | XML | +| `.json` | JSON | +| `.yaml`, `.yml` | YAML | + +If your file uses a non-standard extension (or no extension), you can override automatic detection: + +```bash +oscal-cli convert --as=xml --to=json input.txt output.json +``` + +## Output Options + +### Write to Standard Output + +Omit the output file to write to stdout: + +```bash +oscal-cli convert --to=json catalog.xml +``` + +### Overwrite Existing Files + +```bash +oscal-cli convert --to=json --overwrite catalog.xml catalog.json +``` + +## Converting All OSCAL Document Types + +Conversion works the same way for all OSCAL document types. The CLI detects the document type from the content and applies the appropriate conversion rules. Here are examples for each type: + +### Catalogs + +```bash +oscal-cli convert --to=json NIST_SP-800-53_catalog.xml NIST_SP-800-53_catalog.json +``` + +### Profiles + +```bash +oscal-cli convert --to=xml FedRAMP_HIGH_profile.json FedRAMP_HIGH_profile.xml +``` + +### Mapping Collections + +```bash +oscal-cli convert --to=json mapping.xml mapping.json +``` + +### System Security Plans + +```bash +oscal-cli convert --to=yaml ssp.json ssp.yaml +``` + +### Component Definitions + +```bash +oscal-cli convert --to=json component-definition.xml component-definition.json +``` + +### Assessment Artifacts + +```bash +# Assessment Plans +oscal-cli convert --to=json assessment-plan.xml assessment-plan.json + +# Assessment Results +oscal-cli convert --to=json assessment-results.xml assessment-results.json + +# POA&Ms +oscal-cli convert --to=json poam.xml poam.json +``` + +## Batch Conversion + +When migrating a collection of documents to a new format, shell scripting handles the repetitive work. The following examples show how to convert multiple files at once: + +### Convert All XML to JSON + +#[[ +```bash +for f in *.xml; do + oscal-cli convert --to=json "$f" "${f%.xml}.json" +done +``` +]]# + +### Convert Using Find + +#[[ +```bash +find . -name "*.xml" -exec sh -c ' + oscal-cli convert --to=json "$1" "${1%.xml}.json" +' _ {} \; +``` +]]# + +## Container Usage + +Docker provides a convenient way to run conversions without installing Java locally. Mount your working directory into the container to access your files: + +#[[ +```bash +# Convert a single file +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + convert --to=json /data/catalog.xml /data/catalog.json + +# Convert all XML files to JSON +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + sh -c 'for f in /data/*.xml; do + oscal-cli convert --to=json "$f" "${f%.xml}.json" + done' +``` +]]# + +## CI/CD Integration + +Automated format conversion is useful when publishing artifacts—for example, generating JSON versions of XML source files when creating a release: + +### GitHub Actions - Convert on Release + +#[[ +```yaml +- name: Generate JSON from XML + run: | + for xml in src/oscal/*.xml; do + json="${xml%.xml}.json" + oscal-cli convert --to=json "$xml" "$json" + done + +- name: Upload JSON artifacts + uses: actions/upload-artifact@v4 + with: + name: oscal-json + path: src/oscal/*.json +``` +]]# + +## Format Considerations + +Choosing a format depends on your use case. Each format has trade-offs that may influence your decision. The following tables summarize the key differences: + +### XML vs JSON + +| Aspect | XML | JSON | +|:-------|:----|:-----| +| Human readability | Good with formatting | Good | +| File size | Larger | Smaller | +| Comments | Supported | Not supported | +| Namespace support | Full | Via properties | +| Tool support | XPath, XSLT | Widespread | + +### YAML vs JSON + +| Aspect | YAML | JSON | +|:-------|:-----|:-----| +| Human readability | Excellent | Good | +| Editing | Easy | Standard | +| Comments | Supported | Not supported | +| Whitespace | Significant | Ignored | +| Parsing speed | Slower | Faster | + +## Troubleshooting + +When conversion fails, the error messages point to the issue. Here are solutions for common problems: + +### Invalid Input Format + +``` +Error: Unable to determine format for file 'document.txt' +``` + +**Fix:** Use `--as` to specify input format: + +```bash +oscal-cli convert --as=json --to=xml document.txt output.xml +``` + +### Conversion Errors + +``` +Error: Failed to parse input document +``` + +**Fix:** Validate the input first: + +```bash +oscal-cli validate input.json +oscal-cli convert --to=xml input.json output.xml +``` + +## Next Steps + +Continue learning about the OSCAL CLI with these related guides: + +- [Validating OSCAL](validating-oscal.html) - Validate before converting +- [Resolving Profiles](resolving-profiles.html) - Resolve profiles to catalogs +- [CLI Reference](cli-reference.html) - Complete command reference diff --git a/src/site/markdown/guides/resolving-profiles.md.vm b/src/site/markdown/guides/resolving-profiles.md.vm new file mode 100644 index 00000000..6a0426b7 --- /dev/null +++ b/src/site/markdown/guides/resolving-profiles.md.vm @@ -0,0 +1,253 @@ +# Resolving Profiles + +This guide explains how to resolve OSCAL profiles into baseline catalogs using the oscal-cli. + +## Why Resolve Profiles? + +OSCAL profiles are references to controls in external catalogs, combined with customizations. While profiles are powerful for defining baselines without duplicating content, many tools and workflows need a complete, self-contained catalog. Profile resolution solves this by: + +- **Flattening references** - Converting profile imports into actual control content +- **Applying customizations** - Incorporating all parameter settings and modifications +- **Creating portability** - Producing standalone documents that don't require network access +- **Enabling comparison** - Making it easier to diff two baselines or audit changes +- **Supporting downstream tools** - Many GRC tools expect catalogs, not profiles + +For example, your organization's security profile might import FedRAMP High and add custom parameters. Resolution produces a single catalog containing exactly the controls your organization uses, with your specific parameter values already set. + +## Overview + +OSCAL profiles select and customize controls from one or more catalogs. Profile resolution produces a **resolved catalog** containing only the selected controls with all customizations applied. + +## What Profile Resolution Does + +1. **Imports** controls from referenced catalogs +2. **Selects** specific controls or control families +3. **Excludes** unwanted controls +4. **Modifies** control content (parameters, additions, alterations) +5. **Merges** controls from multiple sources +6. **Outputs** a single, self-contained catalog + +## Basic Resolution + +### Resolve a Profile + +```bash +oscal-cli resolve-profile profile.json resolved-catalog.json +``` + +### Resolve XML Profile + +```bash +oscal-cli resolve-profile profile.xml resolved-catalog.xml +``` + +## Output Formats + +By default, the resolved catalog uses the same format as the input profile. You can convert to a different format during resolution, avoiding a separate conversion step: + +### Convert Format During Resolution + +```bash +# XML profile to JSON catalog +oscal-cli resolve-profile --to=json profile.xml resolved-catalog.json + +# JSON profile to XML catalog +oscal-cli resolve-profile --to=xml profile.json resolved-catalog.xml +``` + +### Output to Standard Out + +```bash +oscal-cli resolve-profile --to=json profile.xml +``` + +## Resolving Common Profiles + +### NIST SP 800-53 Baselines + +```bash +# Resolve FedRAMP High baseline +oscal-cli resolve-profile \ + fedramp-high-profile.json \ + fedramp-high-resolved-catalog.json +``` + +### Custom Organizational Profiles + +```bash +# Resolve your organization's profile +oscal-cli resolve-profile \ + org-baseline-profile.json \ + org-baseline-catalog.json +``` + +## Profile Chaining + +Profiles can import other profiles, creating a layered customization chain. This is common in organizations where a base profile establishes core requirements and subsidiary profiles add further refinements. Resolution handles these chains automatically—it recursively resolves all imported profiles: + +``` +Catalog → Base Profile → Organization Profile → Project Profile + ↓ + Resolved Catalog +``` + +```bash +# This resolves the entire chain +oscal-cli resolve-profile project-profile.json resolved.json +``` + +## Working with Remote Resources + +Profiles often reference catalogs and other profiles hosted on external servers. The CLI fetches these resources automatically during resolution, so you don't need to download them manually: + +### Resolve Profile with Remote Catalog + +```bash +oscal-cli resolve-profile profile.json resolved-catalog.json +``` + +The profile can reference remote catalogs via `href`: + +```json +{ + "import": { + "href": "https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json" + } +} +``` + +### Resolve a Remote Profile + +```bash +oscal-cli resolve-profile \ + https://example.com/profiles/my-profile.json \ + resolved-catalog.json +``` + +## Container Usage + +Docker provides a convenient way to resolve profiles without installing Java. Mount your working directory into the container to access your files: + +```bash +# Resolve a profile with local files +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + resolve-profile /data/profile.json /data/resolved.json + +# Resolve with format conversion +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + resolve-profile --to=xml /data/profile.json /data/resolved.xml +``` + +## CI/CD Integration + +Automating profile resolution in CI/CD ensures resolved catalogs stay synchronized with their source profiles. Whenever a profile changes, the pipeline can automatically regenerate the resolved catalog: + +### Automated Resolution on Change + +#[[ +```yaml +name: Resolve Profiles + +on: + push: + paths: + - 'profiles/**' + +jobs: + resolve: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Resolve profiles + run: | + for profile in profiles/*.json; do + name=$(basename "$profile" .json) + oscal-cli resolve-profile "$profile" "resolved/${name}-catalog.json" + done + + - name: Commit resolved catalogs + run: | + git add resolved/ + git commit -m "Update resolved catalogs" || true + git push +``` +]]# + +## Understanding Resolution Output + +After resolution completes, you have a standard OSCAL catalog with all profile customizations applied. The resolved catalog: + +- Contains only selected controls +- Has all parameter values set +- Includes all modifications and additions +- Is a valid, standalone OSCAL catalog +- Can be used as input to other profiles + +## Troubleshooting + +When resolution fails, the error messages help identify the issue. Here are solutions for common problems: + +### Import Not Found + +``` +Error: Unable to resolve import href 'catalog.json' +``` + +**Fix:** Ensure the referenced file exists or URL is accessible. + +### Circular Import + +``` +Error: Circular import detected +``` + +**Fix:** Check your profile chain for circular references. + +### Invalid Profile Structure + +``` +Error: Invalid profile structure +``` + +**Fix:** Validate the profile first: + +```bash +oscal-cli validate profile.json +``` + +## Profile Resolution Details + +For advanced users who need to understand exactly how resolution works, the following tables describe the behavior of each profile element: + +### What Gets Resolved + +| Element | Resolution Behavior | +|:--------|:--------------------| +| `import/include-all` | All controls from catalog | +| `import/include-controls` | Specific controls by ID | +| `import/exclude-controls` | Remove specific controls | +| `modify/set-parameters` | Set parameter values | +| `modify/alters` | Add or modify control content | +| `merge/combine` | Combine duplicate controls | +| `merge/flat` | Flatten control hierarchy | + +### Resolution Order + +The resolver processes profile elements in a specific order. Understanding this sequence helps when debugging unexpected results: + +1. Process imports (recursively for profile chains) +2. Apply inclusions and exclusions +3. Apply modifications +4. Apply merge settings +5. Generate resolved catalog + +## Next Steps + +Continue learning about the OSCAL CLI with these related guides: + +- [Validating OSCAL](validating-oscal.html) - Validate resolved catalogs +- [Converting Formats](converting-formats.html) - Convert between formats +- [CLI Reference](cli-reference.html) - Complete command reference diff --git a/src/site/markdown/guides/validating-oscal.md.vm b/src/site/markdown/guides/validating-oscal.md.vm new file mode 100644 index 00000000..beec2cb4 --- /dev/null +++ b/src/site/markdown/guides/validating-oscal.md.vm @@ -0,0 +1,245 @@ +# Validating OSCAL Documents + +This guide explains how to validate OSCAL documents using the oscal-cli. + +## Why Validate? + +OSCAL documents are complex structured data that must conform to precise specifications. Validation catches problems early, before invalid documents cause issues in downstream tools or processes. Common problems validation detects include: + +- **Syntax errors** - Malformed XML, JSON, or YAML that can't be parsed +- **Missing required fields** - Required elements like UUIDs, titles, or timestamps +- **Invalid data formats** - UUIDs that aren't valid, dates in wrong formats, etc. +- **Structural violations** - Elements in wrong locations or with invalid cardinality +- **Constraint violations** - Business rules beyond basic schema requirements + +Integrating validation into your workflow—especially in CI/CD pipelines—ensures that OSCAL artifacts meet quality standards before they're used in production. + +## Overview + +The `validate` command checks OSCAL documents at multiple levels: + +- **Well-formedness** - Valid XML, JSON, or YAML syntax +- **Schema compliance** - Conformance to the OSCAL model structure +- **Constraint validation** - Metaschema-defined validation rules that express business logic beyond basic schema requirements + +## Basic Validation + +### Validate a Single File + +```bash +# Validate JSON +oscal-cli validate ssp.json + +# Validate XML +oscal-cli validate catalog.xml + +# Validate YAML +oscal-cli validate profile.yaml +``` + +### Validate with Verbose Output + +```bash +oscal-cli validate --show-stack-trace ssp.json +``` + +## Validation Modes + +### Well-formedness Only + +Check only that the document is valid XML/JSON/YAML: + +```bash +oscal-cli validate --as=xml catalog.xml +``` + +### Full Validation + +Include Metaschema constraint validation (experimental): + +```bash +oscal-cli validate catalog.json +``` + +## Working with Different Document Types + +The CLI automatically detects the OSCAL document type from the content. You can validate any type with the same command—the CLI inspects the root element to determine validation rules. The following examples demonstrate validation for each supported document type: + +### Catalogs + +```bash +oscal-cli validate /path/to/catalog.json +``` + +### Profiles + +```bash +oscal-cli validate /path/to/profile.json +``` + +### Mapping Collections + +```bash +oscal-cli validate /path/to/mapping.json +``` + +### System Security Plans (SSPs) + +```bash +oscal-cli validate /path/to/ssp.json +``` + +### Component Definitions + +```bash +oscal-cli validate /path/to/component-definition.json +``` + +### Assessment Plans + +```bash +oscal-cli validate /path/to/assessment-plan.json +``` + +### Assessment Results + +```bash +oscal-cli validate /path/to/assessment-results.json +``` + +### POA&Ms + +```bash +oscal-cli validate /path/to/poam.json +``` + +## Validating Remote Files + +Validate files directly from URLs: + +```bash +oscal-cli validate https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json +``` + +## Understanding Validation Output + +The validator reports issues in a structured format that helps you locate and fix problems. Here's what to expect: + +### Success + +A successful validation produces minimal output: + +``` +Validation completed with 0 errors. +``` + +### Errors + +When validation fails, each issue is reported with its location and description: + +``` +[ERROR] /document/metadata/title: Required field 'title' is missing +``` + +Each error message includes three pieces of information: +- Severity level (ERROR, WARNING, INFO) +- JSON Pointer or XPath location +- Description of the issue + +## Common Validation Errors + +The following examples show frequent validation errors and how to fix them. These cover the most common issues you'll encounter when working with OSCAL documents: + +### Missing Required Fields + +``` +[ERROR] /catalog/metadata: Required property 'title' is missing +``` + +**Fix:** Add the required field to your document. + +### Invalid UUID Format + +``` +[ERROR] /catalog/uuid: Value 'not-a-uuid' is not a valid UUID +``` + +**Fix:** Use a valid UUID v4 format. + +### Invalid Date-Time + +``` +[ERROR] /catalog/metadata/last-modified: Value is not a valid date-time +``` + +**Fix:** Use ISO 8601 format: `2024-01-15T10:30:00Z` + +### Invalid Reference + +``` +[ERROR] /profile/imports/0/href: Referenced resource not found +``` + +**Fix:** Ensure the referenced file exists or URL is accessible. + +## Batch Validation + +When managing multiple OSCAL documents, you can validate them in bulk using shell scripting. This is particularly useful for pre-commit checks or CI/CD pipelines: + +```bash +# Using shell expansion +for f in *.json; do + echo "Validating $f" + oscal-cli validate "$f" +done + +# Using find +find . -name "*.json" -exec oscal-cli validate {} \; +``` + +## Container Usage + +If you're using Docker, you can run the CLI without installing Java. Mount your local files into the container to validate them: + +```bash +# Validate a local file +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/ssp.json + +# Validate multiple files +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + sh -c 'for f in /data/*.json; do oscal-cli validate "$f"; done' +``` + +## CI/CD Integration + +Integrating validation into your CI/CD pipeline ensures OSCAL artifacts are checked automatically on every commit or pull request. Here's an example for GitHub Actions: + +### GitHub Actions + +```yaml +- name: Validate OSCAL + run: | + for file in $(find . -name "*.json" -path "*/oscal/*"); do + oscal-cli validate "$file" + done +``` + +### Exit Codes + +The CLI uses standard exit codes that work well with CI/CD systems—zero means success, non-zero means failure: + +| Code | Meaning | +|:-----|:--------| +| 0 | Validation passed | +| 1 | Validation failed | +| 2 | Invalid arguments or file not found | + +## Next Steps + +Continue learning about the OSCAL CLI with these related guides: + +- [Converting Formats](converting-formats.html) - Convert between XML, JSON, YAML +- [CLI Reference](cli-reference.html) - Complete command reference diff --git a/src/site/markdown/guides/working-with-metaschema.md.vm b/src/site/markdown/guides/working-with-metaschema.md.vm new file mode 100644 index 00000000..c0089ab1 --- /dev/null +++ b/src/site/markdown/guides/working-with-metaschema.md.vm @@ -0,0 +1,235 @@ +# Working with Metaschema + +This guide explains how to use the oscal-cli for Metaschema-related operations. + +## Overview + +The oscal-cli includes Metaschema functionality inherited from metaschema-cli, including: + +- Evaluating Metapath expressions against OSCAL documents +- Understanding OSCAL's Metaschema-defined structure +- Working with Metaschema constraint validation + +## Evaluating Metapath Expressions + +Metapath is an XPath-like expression language designed for querying Metaschema-based documents. Unlike XPath, which is XML-specific, Metapath works identically regardless of whether your document is in XML, JSON, or YAML format. + +### Basic Query + +```bash +oscal-cli metapath eval -e "//control" catalog.json +``` + +### Query with Output Format + +```bash +oscal-cli metapath eval -e "//control/title" --to=json catalog.json +``` + +### Common Metapath Queries for OSCAL + +The following examples demonstrate frequently used queries for OSCAL documents. These patterns form the foundation for more complex queries: + +#### Find All Controls + +```bash +oscal-cli metapath eval -e "//control" catalog.json +``` + +#### Find Controls by ID Pattern + +```bash +oscal-cli metapath eval -e "//control[starts-with(@id, 'ac-')]" catalog.json +``` + +#### Get Control Titles + +```bash +oscal-cli metapath eval -e "//control/title" catalog.json +``` + +#### Find Controls with Specific Property + +```bash +oscal-cli metapath eval -e "//control[prop[@name='label']]" catalog.json +``` + +#### Count Controls + +```bash +oscal-cli metapath eval -e "count(//control)" catalog.json +``` + +#### Find Parameters + +```bash +oscal-cli metapath eval -e "//param" catalog.json +``` + +## Metapath Expression Syntax + +If you're familiar with XPath, Metapath syntax will feel natural. The following tables provide a quick reference for common patterns: + +### Path Expressions + +Path expressions navigate the document structure. The `//` operator is particularly useful for finding elements at any depth: + +| Expression | Description | +|:-----------|:------------| +| `/catalog` | Root catalog element | +| `//control` | All controls at any depth | +| `control/part` | Parts within controls | +| `..` | Parent element | +| `.` | Current element | + +### Predicates + +Predicates filter results based on conditions. They appear in square brackets after the element selector: + +| Expression | Description | +|:-----------|:------------| +| `control[@id='ac-1']` | Control with specific ID | +| `control[1]` | First control | +| `control[last()]` | Last control | +| `control[position() < 5]` | First four controls | + +### Functions + +Built-in functions perform calculations and string operations. They can be used in predicates or as the expression itself: + +| Function | Description | +|:---------|:------------| +| `count(//control)` | Count controls | +| `string-length(title)` | Length of title | +| `starts-with(@id, 'ac')` | ID starts with 'ac' | +| `contains(title, 'Access')` | Title contains 'Access' | + +### OSCAL-Specific Functions + +These functions are specific to OSCAL and are registered by the OSCAL CLI: + +| Function | Description | +|:---------|:------------| +| `has-oscal-namespace(prop, 'https://fedramp.gov/ns/oscal')` | Check property namespace | +| `resolve-profile(import)` | Resolve profile import | + +## Container Usage + +Docker lets you run Metapath queries without installing Java. Mount your local directory to access your OSCAL documents: + +```bash +# Evaluate Metapath query +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + metapath eval -e "//control" /data/catalog.json + +# Query with formatted output +docker run --rm -v "$(pwd):/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + metapath eval -e "//control/title" --to=json /data/catalog.json +``` + +## Practical Examples + +The following examples show real-world query patterns you might use when working with OSCAL catalogs. These combine the path expressions, predicates, and functions covered above: + +### List All Control IDs + +```bash +oscal-cli metapath eval -e "//control/@id" catalog.json +``` + +### Find Enhancement Controls + +```bash +oscal-cli metapath eval -e "//control[contains(@id, '.')]" catalog.json +``` + +### Find Withdrawn Controls + +```bash +oscal-cli metapath eval -e "//control[prop[@name='status'][@value='withdrawn']]" catalog.json +``` + +### Get Control Statements + +```bash +oscal-cli metapath eval -e "//control[@id='ac-1']/part[@name='statement']" catalog.json +``` + +### Find Controls Referencing a Parameter + +```bash +oscal-cli metapath eval -e "//control[.//insert[@type='param'][@id-ref='ac-1_prm_1']]" catalog.json +``` + +## Understanding OSCAL's Metaschema + +Behind the scenes, OSCAL documents are defined by Metaschema module specifications. Understanding this foundation helps you write better queries and interpret validation errors. Metaschema specifies: + +- **Model structure** - Assemblies, fields, flags that define the document hierarchy +- **Data types** - UUID, date-time, markup-line, and other value constraints +- **Constraints** - Required fields, cardinality limits, and validation patterns + +### OSCAL Model Modules + +The OSCAL specification is divided into modules, each defining a specific document type: + +| Module | Content | +|:-------|:--------| +| `oscal_catalog` | Catalogs, groups, controls | +| `oscal_profile` | Profiles and imports | +| `oscal_ssp` | System Security Plans | +| `oscal_component-definition` | Component definitions | +| `oscal_assessment-plan` | Assessment plans | +| `oscal_assessment-results` | Assessment results | +| `oscal_poam` | Plans of Action and Milestones | + +## CI/CD Integration + +Metapath queries can extract data for use in CI/CD workflows—generating reports, validating control counts, or creating derived artifacts: + +### Extract Control Information + +```yaml +- name: List control IDs + run: | + oscal-cli metapath eval -e "//control/@id" catalog.json > control-ids.txt + +- name: Count controls + run: | + count=$(oscal-cli metapath eval -e "count(//control)" catalog.json) + echo "Catalog contains $count controls" +``` + +## Troubleshooting + +Common issues when working with Metapath expressions and their solutions: + +### Invalid Expression + +``` +Error: Invalid Metapath expression +``` + +**Fix:** Check expression syntax. Use single quotes around string literals: + +```bash +oscal-cli metapath eval -e "//control[@id='ac-1']" catalog.json +``` + +### No Results + +If the query returns nothing: + +1. Verify the document structure +2. Check element names and paths +3. Try a broader query first: `//control` + +## Next Steps + +Continue learning about the OSCAL CLI with these related guides: + +- [Validating OSCAL](validating-oscal.html) - Validate with constraints +- [CLI Reference](cli-reference.html) - Complete command reference +- [Metapath Reference](https://framework.metaschema.dev/specification/metapath/) - Full Metapath specification diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm index afd6378f..e84c5554 100644 --- a/src/site/markdown/index.md.vm +++ b/src/site/markdown/index.md.vm @@ -1,12 +1,150 @@ # ${project.name} -This open-source, tool offers a convenient way to manipulate OSCAL and Metaschema based -content supporting the following operations: +A command-line tool for working with [OSCAL](https://pages.nist.gov/OSCAL/) (Open Security Controls Assessment Language) and [Metaschema](https://framework.metaschema.dev/) content. -- Converting OSCAL content between the OSCAL XML, JSON, and YAML formats. -- Validating an OSCAL resources to ensure it is well-formed and valid. -- Resolving OSCAL Profiles. -- Validating a Metaschema model definition to ensure it is well-formed and valid. -- Generating XML and JSON Schemas from a Metaschema model definition. +## What is the OSCAL CLI? -For usage instructions, please goto https://github.com/metaschema-framework/oscal-cli. +The OSCAL CLI is a cross-platform command-line tool that provides essential operations for working with OSCAL documents. Whether you're validating compliance artifacts, converting between formats, or resolving profiles, the CLI offers a straightforward interface that works in interactive sessions and automated pipelines alike. + +The CLI is particularly useful for: + +- **CI/CD integration** - Validate OSCAL documents automatically as part of your build pipeline +- **Format standardization** - Convert OSCAL content to your organization's preferred format +- **Profile resolution** - Generate resolved catalogs from OSCAL profiles +- **Scripting and automation** - Incorporate OSCAL processing into shell scripts and workflows +- **Learning OSCAL** - Experiment with OSCAL documents without writing code + +## Why Use This Tool? + +The OSCAL CLI provides a batteries-included approach to OSCAL processing: + +- **No coding required** - Perform common OSCAL operations without writing Java or other code +- **Format agnostic** - Work with XML, JSON, and YAML interchangeably +- **Standards compliant** - Built on the same libraries used by NIST for OSCAL reference implementations +- **Container ready** - Available as a Docker/Podman image for easy deployment +- **Cross-platform** - Runs anywhere Java runs: Linux, macOS, Windows + +For programmatic access to OSCAL functionality, see [liboscal-java](https://github.com/metaschema-framework/liboscal-java), the Java library this CLI is built on. + +## Quick Start + +### Using Docker + +```bash +# Validate an OSCAL document +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/ssp.json + +# Convert XML to JSON +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + convert --to=json /data/catalog.xml /data/catalog.json +``` + +### Using the CLI Directly + +```bash +# Validate an OSCAL document +oscal-cli validate ssp.json + +# Convert between formats +oscal-cli convert --to=json catalog.xml catalog.json + +# Resolve a profile +oscal-cli resolve-profile profile.json resolved-catalog.json +``` + +See the [Installation](installation.html) guide for download and setup instructions. + +## Key Features + +### Validation + +Validate OSCAL documents to ensure they conform to the OSCAL specification. The CLI checks for well-formedness, schema compliance, and optionally validates against Metaschema constraints that express business rules beyond basic schema requirements. Validation errors include detailed messages with line numbers and context to help you quickly identify and fix issues. + +### Format Conversion + +Convert OSCAL documents between XML, JSON, and YAML formats with full fidelity. The CLI preserves all data during conversion—you can round-trip documents through multiple format changes without data loss. This is useful for standardizing on a single format across your organization or for working with tools that require a specific format. + +### Profile Resolution + +Resolve OSCAL profiles to produce flattened catalogs. Profiles define control baselines by selecting controls from catalogs, modifying parameters, and adding organization-specific guidance. Profile resolution produces a "resolved catalog" that incorporates all these customizations into a single, self-contained document. + +### Metapath Queries + +Query OSCAL content using Metapath, an XPath-like expression language designed for Metaschema-based data. Metapath allows you to extract specific data from documents, count elements, and perform calculations—all from the command line. + +### Schema Generation + +Generate XML Schema (XSD) and JSON Schema files from Metaschema module definitions. This is primarily useful for developers working with custom Metaschema models beyond OSCAL. + +## Common Commands + +| Command | Description | +|---------|-------------| +| `validate` | Validate an OSCAL or Metaschema document | +| `convert` | Convert between XML, JSON, and YAML formats | +| `resolve-profile` | Resolve an OSCAL profile to a catalog | +| `metapath eval` | Evaluate Metapath expressions | +| `shell-completion` | Generate shell completion scripts | + +## Getting Started + +| Task | Guide | +|:-----|:------| +| Install the CLI | [Installation](installation.html) | +| Build from source | [Building](building.html) | +| Validate documents | [Validating OSCAL](guides/validating-oscal.html) | +| Convert formats | [Converting Formats](guides/converting-formats.html) | +| Resolve profiles | [Resolving Profiles](guides/resolving-profiles.html) | +| Query with Metapath | [Working with Metaschema](guides/working-with-metaschema.html) | +| Command reference | [CLI Reference](guides/cli-reference.html) | + +## Container Usage + +The CLI is available as a container image: + +```bash +# Pull the image +docker pull ghcr.io/metaschema-framework/oscal-cli:latest + +# Run with mounted volume +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/document.json +``` + +See the [Installation](installation.html) guide for CI/CD integration examples. + +## Shell Completion + +Enable tab completion for Bash or Zsh: + +```bash +# Bash +mkdir -p ~/.local/share/bash-completion/completions +oscal-cli shell-completion bash > ~/.local/share/bash-completion/completions/oscal-cli + +# Zsh +mkdir -p ~/.zsh/completions +oscal-cli shell-completion zsh > ~/.zsh/completions/_oscal-cli +``` + +## Related Projects + +This CLI is part of a larger ecosystem of OSCAL and Metaschema tools: + +| Project | Description | +|:--------|:------------| +| [liboscal-java](https://github.com/metaschema-framework/liboscal-java) | OSCAL Java library | +| [metaschema-java](https://github.com/metaschema-framework/metaschema-java) | Core Metaschema framework | +| [OSCAL](https://pages.nist.gov/OSCAL/) | OSCAL specification and documentation | + +## Using with Claude Code + +This project includes plugins for [Claude Code](https://claude.ai/code) that provide AI-assisted development. See the [Claude Integration](claude-integration.html) guide for details. + +## Support + +Have questions or found an issue? Here's how to get help: + +- [GitHub Issues](${project.issueManagement.url}) - Report bugs or request features +- [Contributing](${project.scm.url}/blob/HEAD/CONTRIBUTING.md) - Contribution guidelines diff --git a/src/site/markdown/installation.md.vm b/src/site/markdown/installation.md.vm new file mode 100644 index 00000000..1e96900e --- /dev/null +++ b/src/site/markdown/installation.md.vm @@ -0,0 +1,228 @@ +# Installation + +This guide explains how to install and set up the OSCAL CLI tool. + +## Choosing an Installation Method + +The OSCAL CLI can be installed in several ways depending on your needs: + +| Method | Best for | +|:-------|:---------| +| **Container (Docker/Podman)** | CI/CD pipelines, isolated environments, quick testing without Java installation | +| **Direct download** | Desktop use, permanent installation, shell completion support | +| **Build from source** | Contributing to development, customizing the CLI, accessing unreleased features | + +For most users, the container image is the simplest way to get started—it requires no Java installation and works identically across all platforms. For regular desktop use, the direct download provides shell completion and faster startup times. + +## Prerequisites + +If you're using the container image, you only need Docker or Podman installed. For direct installation, you'll need Java: + +| Requirement | Minimum Version | Notes | +|:------------|:----------------|:------| +| Java JRE | 11 | JRE 17+ recommended for best performance | + +Ensure Java is installed and available on your PATH: + +```bash +java -version +``` + +## Quick Start + +Download the latest release and run. Replace `VERSION` with the actual version number from [Maven Central](https://central.sonatype.com/artifact/dev.metaschema.oscal/oscal-cli-enhanced): + +```bash +# Set the version (check Maven Central for the latest) +VERSION="2.0.0" + +# Download and extract +curl -L "https://repo1.maven.org/maven2/dev/metaschema/oscal/oscal-cli-enhanced/${VERSION}/oscal-cli-enhanced-${VERSION}-oscal-cli.zip" -o oscal-cli.zip +unzip oscal-cli.zip + +# Run +./oscal-cli --help +``` + +## Installation Methods + +### Download from Maven Central + +Release versions are published to Maven Central and provide the most stable experience: + +1. Go to [Maven Central](https://central.sonatype.com/artifact/dev.metaschema.oscal/oscal-cli-enhanced) +2. Download the `-oscal-cli.zip` distribution (look for the file ending in `-oscal-cli.zip`) +3. Extract to your preferred location (e.g., `/opt/oscal-cli` or `C:\Program Files\oscal-cli`) +4. Add the extracted `bin/` directory to your PATH + +After installation, the `oscal-cli` command will be available from any terminal. + +### Download Snapshot Versions + +Snapshot versions contain the latest changes from the `develop` branch. These include new features and bug fixes that haven't been released yet, but may be less stable: + +1. Browse the [snapshot repository](https://raw.githubusercontent.com/metaschema-framework/maven2/refs/heads/main/dev/metaschema/oscal/oscal-cli-enhanced/) +2. Download the latest `-oscal-cli.zip` file +3. Extract and add to PATH + +### Container Images + +Container images provide an isolated environment with no Java installation required. The image is built on a minimal base and includes everything needed to run the CLI. + +#### Docker + +```bash +# Pull the image +docker pull ghcr.io/metaschema-framework/oscal-cli:latest + +# Run a command +docker run --rm ghcr.io/metaschema-framework/oscal-cli:latest --help + +# Validate a file (with volume mount) +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/ssp.json +``` + +#### Podman + +```bash +# Pull the image +podman pull ghcr.io/metaschema-framework/oscal-cli:latest + +# Run a command +podman run --rm ghcr.io/metaschema-framework/oscal-cli:latest --help + +# Validate a file +podman run --rm -v "$(pwd):/data:Z" ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/ssp.json +``` + +### Working with Mounted Volumes + +When using containers, mount your working directory to access local files: + +```bash +# Mount current directory as /data +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/my-catalog.xml + +# Convert with output file +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + convert --to=json /data/catalog.xml /data/catalog.json + +# Resolve a profile +docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \ + resolve-profile /data/profile.xml /data/resolved-catalog.xml +``` + +## CI/CD Integration + +The OSCAL CLI integrates easily into CI/CD pipelines to validate OSCAL documents automatically. This ensures that compliance artifacts remain valid as they evolve and catches errors before they reach production. + +### GitHub Actions + +#[[ +```yaml +name: Validate OSCAL + +on: [push, pull_request] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate OSCAL files + run: | + docker run --rm -v "${{ github.workspace }}:/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/ssp.json +``` +]]# + +### GitLab CI + +```yaml +validate-oscal: + image: ghcr.io/metaschema-framework/oscal-cli:latest + script: + - oscal-cli validate ssp.json +``` + +### Jenkins Pipeline + +#[[ +```groovy +pipeline { + agent any + stages { + stage('Validate OSCAL') { + steps { + sh ''' + docker run --rm -v "${WORKSPACE}:/data" \ + ghcr.io/metaschema-framework/oscal-cli:latest \ + validate /data/ssp.json + ''' + } + } + } +} +``` +]]# + +## Shell Completion + +Shell completion enables tab completion for commands, options, and file paths, making the CLI faster and easier to use. The CLI supports both Bash and Zsh. + +### Bash + +```bash +# Generate completion script +oscal-cli shell-completion bash > oscal-cli-completion.bash + +# Source for current session +source oscal-cli-completion.bash + +# Or install permanently +mkdir -p ~/.local/share/bash-completion/completions +oscal-cli shell-completion bash > ~/.local/share/bash-completion/completions/oscal-cli +``` + +### Zsh + +```zsh +# Generate completion script +oscal-cli shell-completion zsh > _oscal-cli + +# Install to your fpath (create directory if needed) +mkdir -p ~/.zsh/completions +mv _oscal-cli ~/.zsh/completions/ + +# Rebuild completion cache +rm -f ~/.zcompdump && compinit +``` + +## Verifying Installation + +Verify the CLI is working correctly: + +```bash +# Check version +oscal-cli --version + +# View available commands +oscal-cli --help + +# Validate a sample file +oscal-cli validate https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json +``` + +## Next Steps + +Now that you have the CLI installed, explore these guides to start working with OSCAL: + +- [Validating OSCAL](guides/validating-oscal.html) - Validate OSCAL documents +- [Converting Formats](guides/converting-formats.html) - Convert between XML, JSON, and YAML +- [Resolving Profiles](guides/resolving-profiles.html) - Resolve profiles to catalogs +- [CLI Reference](guides/cli-reference.html) - Complete command reference diff --git a/src/site/resources/css/custom.css b/src/site/resources/css/custom.css index 2c3aa8f8..f03f5258 100644 --- a/src/site/resources/css/custom.css +++ b/src/site/resources/css/custom.css @@ -19,4 +19,11 @@ footer { code { color: #5f879b; +} + +/* Fix table header alignment - flexmark doesn't apply alignment to cells */ +/* Use higher specificity to override Bootstrap's .table th styles */ +.table th, +table th { + text-align: left !important; } \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index ac62b74a..798a7d94 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -49,6 +49,18 @@ + + + + + + + + + + + +