From dcbccd63116ba8df1382d5657af77e8f48d4a27c Mon Sep 17 00:00:00 2001 From: Brandt Keller Date: Sat, 17 Aug 2024 02:57:32 +0000 Subject: [PATCH 1/3] feat(internal): add docs generation command --- docs/cli-commands/assessments/README.md | 10 - docs/cli-commands/assessments/assess.md | 8 - docs/cli-commands/assessments/evaluate.md | 68 ----- docs/cli-commands/assessments/validate.md | 23 -- docs/cli-commands/dev/README.md | 3 - docs/cli-commands/dev/get_resources.md | 44 ---- docs/cli-commands/dev/lint.md | 30 --- docs/cli-commands/dev/validate.md | 46 ---- docs/cli-commands/generation/README.md | 13 - docs/cli-commands/generation/component.md | 48 ---- .../generation/system-security-plan.md | 247 ------------------ docs/cli-commands/lula.md | 30 +++ docs/cli-commands/lula_completion.md | 35 +++ docs/cli-commands/lula_completion_bash.md | 54 ++++ docs/cli-commands/lula_completion_fish.md | 45 ++++ .../lula_completion_powershell.md | 42 +++ docs/cli-commands/lula_completion_zsh.md | 56 ++++ docs/cli-commands/lula_dev.md | 28 ++ docs/cli-commands/lula_dev_get-resources.md | 56 ++++ docs/cli-commands/lula_dev_lint.md | 44 ++++ docs/cli-commands/lula_dev_validate.md | 58 ++++ docs/cli-commands/lula_evaluate.md | 52 ++++ docs/cli-commands/lula_generate.md | 28 ++ docs/cli-commands/lula_generate_component.md | 56 ++++ docs/cli-commands/lula_tools.md | 29 ++ docs/cli-commands/lula_tools_compose.md | 47 ++++ docs/cli-commands/lula_tools_lint.md | 45 ++++ docs/cli-commands/lula_tools_upgrade.md | 46 ++++ docs/cli-commands/lula_tools_uuidgen.md | 45 ++++ docs/cli-commands/lula_validate.md | 55 ++++ docs/cli-commands/lula_version.md | 42 +++ docs/cli-commands/tools/README.md | 3 - docs/cli-commands/tools/compose.md | 30 --- docs/cli-commands/tools/lint.md | 32 --- docs/cli-commands/tools/uuidgen.md | 9 - go.mod | 1 + go.sum | 1 + src/cmd/internal.go | 78 ++++++ 38 files changed, 973 insertions(+), 614 deletions(-) delete mode 100644 docs/cli-commands/assessments/README.md delete mode 100644 docs/cli-commands/assessments/assess.md delete mode 100644 docs/cli-commands/assessments/evaluate.md delete mode 100644 docs/cli-commands/assessments/validate.md delete mode 100644 docs/cli-commands/dev/README.md delete mode 100644 docs/cli-commands/dev/get_resources.md delete mode 100644 docs/cli-commands/dev/lint.md delete mode 100644 docs/cli-commands/dev/validate.md delete mode 100644 docs/cli-commands/generation/README.md delete mode 100644 docs/cli-commands/generation/component.md delete mode 100644 docs/cli-commands/generation/system-security-plan.md create mode 100644 docs/cli-commands/lula.md create mode 100644 docs/cli-commands/lula_completion.md create mode 100644 docs/cli-commands/lula_completion_bash.md create mode 100644 docs/cli-commands/lula_completion_fish.md create mode 100644 docs/cli-commands/lula_completion_powershell.md create mode 100644 docs/cli-commands/lula_completion_zsh.md create mode 100644 docs/cli-commands/lula_dev.md create mode 100644 docs/cli-commands/lula_dev_get-resources.md create mode 100644 docs/cli-commands/lula_dev_lint.md create mode 100644 docs/cli-commands/lula_dev_validate.md create mode 100644 docs/cli-commands/lula_evaluate.md create mode 100644 docs/cli-commands/lula_generate.md create mode 100644 docs/cli-commands/lula_generate_component.md create mode 100644 docs/cli-commands/lula_tools.md create mode 100644 docs/cli-commands/lula_tools_compose.md create mode 100644 docs/cli-commands/lula_tools_lint.md create mode 100644 docs/cli-commands/lula_tools_upgrade.md create mode 100644 docs/cli-commands/lula_tools_uuidgen.md create mode 100644 docs/cli-commands/lula_validate.md create mode 100644 docs/cli-commands/lula_version.md delete mode 100644 docs/cli-commands/tools/README.md delete mode 100644 docs/cli-commands/tools/compose.md delete mode 100644 docs/cli-commands/tools/lint.md delete mode 100644 docs/cli-commands/tools/uuidgen.md create mode 100644 src/cmd/internal.go diff --git a/docs/cli-commands/assessments/README.md b/docs/cli-commands/assessments/README.md deleted file mode 100644 index ef2a78d4..00000000 --- a/docs/cli-commands/assessments/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Assessment - -The Assessments suite of Lula commands are intended to facilitate the generation of `assessment-plans` and `assessment-results` from `component-defintion` models. The following diagram indicates the OSCAL model inputs, commands, and output OSCAL models expected from each of these commands. - -```mermaid -flowchart TD - A[Component Definition]-->|validate|C[Assessment Results] - A[Component Definition]-->|generate|B[Assessment Plan] - B[Assessment Plan]-->|assess|C[Assessment Results] -``` \ No newline at end of file diff --git a/docs/cli-commands/assessments/assess.md b/docs/cli-commands/assessments/assess.md deleted file mode 100644 index b370db47..00000000 --- a/docs/cli-commands/assessments/assess.md +++ /dev/null @@ -1,8 +0,0 @@ -# Assess - PLANNED - -This command performs the `assessment` between a `component-definition` for a system-level component, outputing the `assessment-plan` OSCAL artifact. - -Use the command as follows: -```shell -lula assess -f oscal-component.yaml -o assessment-plan.yaml -``` diff --git a/docs/cli-commands/assessments/evaluate.md b/docs/cli-commands/assessments/evaluate.md deleted file mode 100644 index a59f37c7..00000000 --- a/docs/cli-commands/assessments/evaluate.md +++ /dev/null @@ -1,68 +0,0 @@ -# Compliance Evaluation - -Evaluate serves as a method for verifying the compliance of a component/system against an established threshold to determine if it is more or less compliant than a previous assessment. - -## Usage - -To evaluate two results (threshold and latest) in a single OSCAL file: -```bash -lula evaluate -f assessment-results.yaml -``` - -To evaluate the latest results in two assessment results files: -```bash -lula evaluate -f assessment-results-threshold.yaml -f assessment-results-new.yaml -``` - -To print a summary of the observation results: -```bash -lula evaluate -f assessment-results.yaml --summary -``` - -To target a specific framework for validation: -```bash -lula evaluate -f assessment-results.yaml --target critical -``` - -## Options - -- `-f, --file`: The path to the file(s) to be evaluated. -- `-s, --summary`: [Optional] Prints a summary of the evaluation. -- `-t, --target`: [Optional] targets a specific standard source or framework - -## Expected Process - -### No Existing Data - -When no previous assessment exists, the initial assessment is made and stored with `lula validate`. Lula will automatically apply the `threshold` prop to the assessment result when writing the assessment result to a file that does not contain an existing assessment results artifact. This initial assessment by itself will always pass `lula evaluate` as there is no threshold for evaluation, and the threshold prop with be set to `true`. - -steps: -1. `lula validate -f component.yaml -o assessment-results.yaml` -2. `lula evaluate -f assessment-results.yaml` -> Passes with no Threshold -> Establishes Threshold - -### Existing Data (Intended Workflow) - -In workflows run manually or with automation (such as CI/CD), there is an expectation that the threshold exists, and evaluate will perform an analysis of the compliance of the system/component against the established threshold. - -steps: -1. `lula validate -f component.yaml -o assessment-results.yaml` -2. `lula evaluate -f assessment-results.yaml` -> Passes or Fails based on threshold - - -## Scenarios for Consideration - -Evaluate will determine which result is the threshold based on the following property: -```yaml -props: - - name: threshold - ns: https://docs.lula.dev/oscal/ns - value: "true/false" -``` - -### Assessment Results Artifact - -When evaluate is ran with a single assessment results artifact, it is expected that a single threshold with a `true` value exists. This will be identified and ran against the latest result to determine if compliance is less-than-equal (fail), equal (pass), or greater-than-equal (pass). When the comparison results in greater-than-equal, Lula will update the threshold `prop` for the latest result to `true` and set the previous result threshold prop to `false`. - -### Comparing multiple assessment results artifacts - -In the scenario where multiple assessment results artifacts are evaluated, there may be a multiple threshold results with a `true` value as Lula establishes a default `true` value when writing an assessment results artifact to a new file with no previous results present. In this case, Lula will use the older result as the threshold to determine compliance of the result. \ No newline at end of file diff --git a/docs/cli-commands/assessments/validate.md b/docs/cli-commands/assessments/validate.md deleted file mode 100644 index 1d5339b7..00000000 --- a/docs/cli-commands/assessments/validate.md +++ /dev/null @@ -1,23 +0,0 @@ -# Validate - -The `validate` command aims to bridge the gap between fully developing the `assessment-plan` and allowing for testing of the existing `component-definition`. - -## Usage - -```bash -lula validate -f /path/to/oscal-component.yaml -``` - -## Options - -- `-f, --input-file`: The path to the OSCAL component definition file. -- `-o, --output-file`: [Optional] The path to the output assessment results file. Creates a new file or appends to existing. If not specified, the output file is `./assessment-results.yaml` -- `-t, --target`: [Optional] The standard/framework to target for assessment -- `--confirm-execution`: [Optional] Flag to skip execution confirmation prompt. Only relevant when running a validation with a domain that performs some execution. -- `--non-interactive`: [Optional] Flag to indicate running non-interactively, i.e., does not request user to confirm validations with execution. - -## Examples - -This command is used both locally as an evaluation of the Component Definition to understand the component's compliance. It's also implemented in CI workflows to continually evaluate the evolution of a system during development. See the following relevant tutorials: - -* [Simple Demo](../../getting-started/simple-demo.md) \ No newline at end of file diff --git a/docs/cli-commands/dev/README.md b/docs/cli-commands/dev/README.md deleted file mode 100644 index 972aeddd..00000000 --- a/docs/cli-commands/dev/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Dev - -Several `dev` commands exist in Lula to facilitate developer methods, such as generating and testing `Lula Validations`. \ No newline at end of file diff --git a/docs/cli-commands/dev/get_resources.md b/docs/cli-commands/dev/get_resources.md deleted file mode 100644 index fd4d43bc..00000000 --- a/docs/cli-commands/dev/get_resources.md +++ /dev/null @@ -1,44 +0,0 @@ -# Get Resources - -The `get-resources` command is used to execute the domain portion of the input Lula Validation manifest to extract the `resources` json. This helps while developing validations to ensure the domain specification is returning the expected resources. - -## Usage - -```bash -lula dev get-resources -f /path/to/validation.yaml -``` - -## Options - -- `-f, --input-file`: The path to the target validation manifest. -- `-o, --output-file`: [Optional] The path to the output file. If not specified, the output will print to STDOUT -- `-t, --timeout`: [Optional] Timeout when waiting for results from STDIN. -- `--confirm-execution`: [Optional] Flag to skip execution confirmation prompt. Only relevant when running a domain that performs some execution. - -## Examples - -To get resources and write to file -```bash -lula dev get-resources -f /path/to/validation.yaml -o /path/to/resources.json -``` - -To run get resources and automatically confirm execution -```bash -lula dev get-resources -f /path/to/validation.yaml --confirm-execution -``` - -To run get resources from stdin -```bash -cat /path/to/validation.yaml | lula dev get-resources -``` - -To hang indefinitely for stdin -```bash -lula dev get-resources -t -1 -``` - -To hang for timeout of 5 seconds -```bash -lula dev get-resources -t 5 -``` - diff --git a/docs/cli-commands/dev/lint.md b/docs/cli-commands/dev/lint.md deleted file mode 100644 index aa433014..00000000 --- a/docs/cli-commands/dev/lint.md +++ /dev/null @@ -1,30 +0,0 @@ -# Lint Command - -The `lula dev lint` command is used to validate validation files against the schema. It can validate both local files and URLs. - -## Usage - -```bash -lula dev lint -f [-r ] -``` - -## Options - -- `-f, --input-files`: The paths to the validation files (comma-separated). -- `-r, --result-file`: The path to the result file. If not specified, the validation results will be printed to the console. - -## Examples - -To lint existing validation files: -```bash -lula dev lint -f ./validation-file1.yaml,./validation-file2.yaml,https://example.com/validation-file3.yaml -``` - -To specify a result file: -```bash -lula dev lint -f ./validation-file1.yaml,./validation-file2.yaml -r validation-results.json -``` - -## Notes - -The validation results will be written to the specified result file. If there is at least one validation result that is not valid, the command will exit with a fatal error listing the files that failed linting. diff --git a/docs/cli-commands/dev/validate.md b/docs/cli-commands/dev/validate.md deleted file mode 100644 index d01f92b6..00000000 --- a/docs/cli-commands/dev/validate.md +++ /dev/null @@ -1,46 +0,0 @@ -# Validate - -The `validate` command is used to run a single validation for the input Lula Validation manifest. This helps while developing validations to exercise the policy engines to ensure correctness and expose the outputs that will appear in the `assessment-results`. - -## Usage - -```bash -lula dev validate -f /path/to/validation.yaml -``` - -## Options - -- `-f, --input-file`: The path to the target validation manifest. -- `-o, --output-file`: [Optional] The path to the output file. If not specified, the output will print to STDOUT -- `-r, --resources-file`: [Optional] The path to the resources file; must be json. If not specified, resources will be read from the domain. -- `-e, --expected-result`: [Optional] The expected result of the validation, true or false. Default is true. -- `-t, --timeout`: [Optional] Timeout when waiting for results from STDIN. -- `--confirm-execution`: [Optional] Flag to skip execution confirmation prompt. Only relevant when running a domain that performs some execution. - -## Examples - -To run validation using a custom resources file -```bash -lula dev validate -f /path/to/validation.yaml -r /path/to/resources.json -``` - -To run validation and automatically confirm execution -```bash -lula dev validate -f /path/to/validation.yaml --confirm-execution -``` - -To run validation from stdin -```bash -cat /path/to/validation.yaml | lula dev validate -``` - -To hang indefinitely for stdin -```bash -lula dev validate -t -1 -``` - -To hang for timeout of 5 seconds -```bash -lula dev validate -t 5 -``` - diff --git a/docs/cli-commands/generation/README.md b/docs/cli-commands/generation/README.md deleted file mode 100644 index 0b274e77..00000000 --- a/docs/cli-commands/generation/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Generation - -Lula can generate OSCAL templates to help with authoring OSCAL artifacts. These generation processes help with initial build and maintenance of OSCAL artifacts and keeps with the vision of modular compliance artifacts that live with the source code. - -Lula currently generates the following OSCAL models: -* Component Definition - -Additional models that Lula is planning to generate via this method include: -* Profile -* System Security Plan, SSP -* Assessment Plan -* Plan of Actions and Milestones, POAM -* Catalog \ No newline at end of file diff --git a/docs/cli-commands/generation/component.md b/docs/cli-commands/generation/component.md deleted file mode 100644 index a1456be4..00000000 --- a/docs/cli-commands/generation/component.md +++ /dev/null @@ -1,48 +0,0 @@ -# Component - -Lula can generate OSCAL templates to help with authoring OSCAL artifacts. These generation processes help with initial build and maintenance of OSCAL artifacts and keeps with the vision of modular compliance artifacts that live with the source code. - -## Component Definition - -To generate a component definition, you need the following context: -- The catalog source `-c` or `--catalog-source`; IE `https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json` -- The controls from the catalog to map to `implemented-requirements` / `-r` or `--requirements`; `ac-1,ac-2,au-5` - -The following command will generate a component definition with the above context: -``` -lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-2,au-5 -``` - -There are optional flags that can be added to the command to generate a component definition: -- The remarks you wish to map from the control parts to the requirement remarks`--remarks`; `assessment-objective,statement,guidance` -- The title of the component `--component`; `Software Title` -- The output file of the component `-o` or `--output`; `oscal-component.yaml` - -### Reproducibility - -The `lula generate` commands are meant to be reproducible and will auto-merge models based on filename. The intent for this generation is to make it easy to update a given model with automation and only inject human intervention as needed. An artifact generated with `lula generate` can be merged with a pre-existing artifact of the same model type. - -For component-definitions, see each individual `control-implementation` props for the `generation` prop. It should look like the following: -```yaml -props: - - name: generation - ns: https://docs.lula.dev/oscal/ns - value: lula generate component --catalog-source https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json --component 'Component Title' --requirements ac-1,ac-3,ac-3.2,ac-4 --remarks assessment-objective -``` - -This `value` should mirror any required inputs in order to reproduce a given control implementation in a component. - -### Existing Data - -The ability to retain data that is put into OSCAL artifacts is of utmost importance to this generation process and also a large feature of continued maintenance of these artifacts. Lula supports the ability to merge newly generated component definition templates into existing component definitions automatically. - -By specifying `--output` or `-o` and providing an existing file - Lula will perform a merge operation that only overwrites specific fields owned by automation. - -Lula performs a match on the component title and the provided catalog source to determine placement and merge of the new implemented requirements. This can be used to updated exiting items or as a method to generation of a single artifacts that contains the data for many components or many control implementations. - -## Example - -```bash -./bin/lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-3,ac-3.2,ac-4 -o oscal-component.yaml --remarks assessment-objective -``` - diff --git a/docs/cli-commands/generation/system-security-plan.md b/docs/cli-commands/generation/system-security-plan.md deleted file mode 100644 index 330d829a..00000000 --- a/docs/cli-commands/generation/system-security-plan.md +++ /dev/null @@ -1,247 +0,0 @@ -# System Security Plan - -**NOTE:** This Document is in an active research phase. - -## System Security Plan Generate - -To generate a system security plan, you need the following context: -- The component definition `--component` -- The profile source `--profile` or catalog source `--catalog`; IE `https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_HIGH-baseline-resolved-profile_catalog.json` - -The following command will generate a system security plan with the above context: - -```bash - -lula generate system-security-plan --component .src/test/unit/valid-component.yaml --catalog https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_HIGH-baseline-resolved-profile_catalog.json - -``` - -There are optional flags that can be added to the command to generate a system security plan: - -- The output file of the component `-o` or `--output`; `oscal-system-security-plan.yaml` - -## System Security Plan Generate Context - -The `system-security-plan` can be generated using the upstream catalog and/or profile in conjunction with the `component-definition`. There are net new fields that are apart of the `system-security-plan` that are not within the `component-definition` or catalog/profile that currently do not make sense to add as props. Those items are under the section `Elements in SSP Not in Component Definition`. There are items that are not in the `system-security-plan` but also not in the `component-definition` that currently do make sense to create as props. Those items are under the section `Elements NOT in Component Definition that need added for SSP Generate`. Lastly as a note there are items within the `component-definition` that are not used in the `system-security-plan` that can be found under the section Elements NOT in `Component Definition that need added for SSP Generate`. - -The items in `Elements in SSP Not in Component Definition` need further context to fill in the missing elements as well as establish data across OSCAL models. Some examples of the data fields are within the `metadata` fields such as `responsible-roles`, `responsible-parties`, and `parties` that can be added to the `system-security-plan` that do not directly map from the `component-definition` field. Additional context can be added through common OSCAL fields such as `props`, `links`, and `remarks`. - -### Further Research Fields - -The following fields need further research to further enhance generating an SSP. - -- `inherited` -- `export` - -### Elements in Component Definition Not in SSP - -- `import-component-definitions` -- `capabilities` - - `uuid` - - `name` - - `description` - - `props` - - `links` - - `incorporates-components` - - `component-uuid` - - `description` - -### Elements in SSP Not in Component Definition - -- `system-characteristics` - - `system-ids` - - `identifier-type` - - `id` - - `system-name` - - `system-name-short` - - `description` - - `security-sensitivity-level` - - `system-information` - - `information-types` - - `id` - - `title` - - `description` - - `security-objective-confidentiality` - - `security-objective-integrity` - - `security-objective-availability` - - `security-impact-level` - - `security-objective-confidentiality` - - `security-objective-integrity` - - `security-objective-availability` - - `status` - - `state` - - `remarks` - - `authorized-boundary` - - `description` - - `props` - - `links` - - `diagrams` - - `uuid` - - `description` - - `props` - - `links` - - `caption` - - `remarks` - - `remarks` - - `network-architecture` - - `description` - - `props` - - `links` - - `diagrams` - - `uuid` - - `description` - - `props` - - `links` - - `caption` - - `remarks` - - `remarks` - - `data-flow` - - `description` - - `props` - - `links` - - `diagrams` - - `uuid` - - `description` - - `props` - - `links` - - `caption` - - `remarks` - - `remarks` - - `props` - - `links` - - `remarks` -- `system-implementation` - - `users` - - `uuid` - - `title` - - `short-name` - - `description` - - `props` - - `links` - - `role-ids` - - `authorized-privileges` - - `title` - - `description` - - `functions-performed` - - `remarks` - - `leveraged-authorizations` - - `uuid` - - `title` - - `props` - - `links` - - `party-uuid` - - `date-authorized` - - `remarks` - - `inventory-items` - - `uuid` - - `description` - - `props` - - `links` - - `remarks` -- `control-implementation` - - `implemented-requirements` - - `statements` - - `satisfied` - - `uuid` - - `responsibility` - - `description` - - `props` - - `links` - - `responsible-roles` - - `role-id` - - `props` - - `links` - - `party-uuid` - - `remarks` - - `role-ids` - - `by-components` - - `satisfied` - - `uuid` - - `responsibility` - - `description` - - `props` - - `links` - - `responsible-roles` - - `role-id` - - `props` - - `links` - - `party-uuid` - - `remarks` - - `role-ids` - -### Elements NOT in Component Definition that need added for SSP Generate - -- `control-implementation` - - `implemented-requirements` - - `by-components` - - `implementation-status` - - `state` - - `remarks` - - `statements` - - `by-components` - - `implementation-status` - - `state` - - `remarks` - -### Component Definition to SSP Transferable Fields - -### **NOTE:** repetitive children elements have been truncated to reduce bloat - -- `metadata` - - `title` - - `published` - - `last-modified` - - `version` - - `oscal-version` - - `revisions` - - `document-ids` - - `props` - - `links` - - `roles` - - `locations` - - `actions` -- `control-implementation` - - `description` - - `set-parameters` - - `param-id` - - `values` - - `remarks` - - `implemented-requirements` - - `uuid` - - `control-id` - - `props` - - `links` - - `set-parameters` - - `param-id` - - `values` - - `remarks` - - `statements` - - `statement-id` - - `props` - - `responsible-roles` - - `links` - - `by-components` - - `by-components` - - `component-uuid` - - `description` - - `props` - - `links` - - `set-parameters` - - `param-id` - - `values` - - `remarks` - - `system-implementation` (Contains Fields from Component Definition) - - `components` - - `uuid` - - `type` - - `title` - - `description` - - `purpose` - - `props` - - `links` - - `status` - - `protocols` - - `implemented-components` - - `component-uuid` - - `props` - - `links` diff --git a/docs/cli-commands/lula.md b/docs/cli-commands/lula.md new file mode 100644 index 00000000..94b0bf28 --- /dev/null +++ b/docs/cli-commands/lula.md @@ -0,0 +1,30 @@ +--- +title: lula +description: Lula CLI command reference for lula. +type: docs +--- +## lula + +Risk Management as Code + +### Synopsis + +Real Time Risk Transparency through automated validation + +### Options + +``` + -h, --help help for lula + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula completion](/cli/cli-commands/lula_completion/) - Generate the autocompletion script for the specified shell +* [lula dev](/cli/cli-commands/lula_dev/) - Collection of dev commands to make dev life easier +* [lula evaluate](/cli/cli-commands/lula_evaluate/) - evaluate two results of a Security Assessment Results +* [lula generate](/cli/cli-commands/lula_generate/) - Generate a specified compliance artifact template +* [lula tools](/cli/cli-commands/lula_tools/) - Collection of additional commands to make OSCAL easier +* [lula validate](/cli/cli-commands/lula_validate/) - validate an OSCAL component definition +* [lula version](/cli/cli-commands/lula_version/) - Shows the current version of the Lula binary + diff --git a/docs/cli-commands/lula_completion.md b/docs/cli-commands/lula_completion.md new file mode 100644 index 00000000..6423406c --- /dev/null +++ b/docs/cli-commands/lula_completion.md @@ -0,0 +1,35 @@ +--- +title: lula completion +description: Lula CLI command reference for lula completion. +type: docs +--- +## lula completion + +Generate the autocompletion script for the specified shell + +### Synopsis + +Generate the autocompletion script for lula for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +### Options + +``` + -h, --help help for completion +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code +* [lula completion bash](/cli/cli-commands/lula_completion_bash/) - Generate the autocompletion script for bash +* [lula completion fish](/cli/cli-commands/lula_completion_fish/) - Generate the autocompletion script for fish +* [lula completion powershell](/cli/cli-commands/lula_completion_powershell/) - Generate the autocompletion script for powershell +* [lula completion zsh](/cli/cli-commands/lula_completion_zsh/) - Generate the autocompletion script for zsh + diff --git a/docs/cli-commands/lula_completion_bash.md b/docs/cli-commands/lula_completion_bash.md new file mode 100644 index 00000000..f5b080ce --- /dev/null +++ b/docs/cli-commands/lula_completion_bash.md @@ -0,0 +1,54 @@ +--- +title: lula completion bash +description: Lula CLI command reference for lula completion bash. +type: docs +--- +## lula completion bash + +Generate the autocompletion script for bash + +### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(lula completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + lula completion bash > /etc/bash_completion.d/lula + +#### macOS: + + lula completion bash > $(brew --prefix)/etc/bash_completion.d/lula + +You will need to start a new shell for this setup to take effect. + + +``` +lula completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula completion](/cli/cli-commands/lula_completion/) - Generate the autocompletion script for the specified shell + diff --git a/docs/cli-commands/lula_completion_fish.md b/docs/cli-commands/lula_completion_fish.md new file mode 100644 index 00000000..dfaee36b --- /dev/null +++ b/docs/cli-commands/lula_completion_fish.md @@ -0,0 +1,45 @@ +--- +title: lula completion fish +description: Lula CLI command reference for lula completion fish. +type: docs +--- +## lula completion fish + +Generate the autocompletion script for fish + +### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + lula completion fish | source + +To load completions for every new session, execute once: + + lula completion fish > ~/.config/fish/completions/lula.fish + +You will need to start a new shell for this setup to take effect. + + +``` +lula completion fish [flags] +``` + +### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula completion](/cli/cli-commands/lula_completion/) - Generate the autocompletion script for the specified shell + diff --git a/docs/cli-commands/lula_completion_powershell.md b/docs/cli-commands/lula_completion_powershell.md new file mode 100644 index 00000000..a43bcba2 --- /dev/null +++ b/docs/cli-commands/lula_completion_powershell.md @@ -0,0 +1,42 @@ +--- +title: lula completion powershell +description: Lula CLI command reference for lula completion powershell. +type: docs +--- +## lula completion powershell + +Generate the autocompletion script for powershell + +### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + lula completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +lula completion powershell [flags] +``` + +### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula completion](/cli/cli-commands/lula_completion/) - Generate the autocompletion script for the specified shell + diff --git a/docs/cli-commands/lula_completion_zsh.md b/docs/cli-commands/lula_completion_zsh.md new file mode 100644 index 00000000..c4d230b9 --- /dev/null +++ b/docs/cli-commands/lula_completion_zsh.md @@ -0,0 +1,56 @@ +--- +title: lula completion zsh +description: Lula CLI command reference for lula completion zsh. +type: docs +--- +## lula completion zsh + +Generate the autocompletion script for zsh + +### Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(lula completion zsh) + +To load completions for every new session, execute once: + +#### Linux: + + lula completion zsh > "${fpath[1]}/_lula" + +#### macOS: + + lula completion zsh > $(brew --prefix)/share/zsh/site-functions/_lula + +You will need to start a new shell for this setup to take effect. + + +``` +lula completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula completion](/cli/cli-commands/lula_completion/) - Generate the autocompletion script for the specified shell + diff --git a/docs/cli-commands/lula_dev.md b/docs/cli-commands/lula_dev.md new file mode 100644 index 00000000..d9776bd3 --- /dev/null +++ b/docs/cli-commands/lula_dev.md @@ -0,0 +1,28 @@ +--- +title: lula dev +description: Lula CLI command reference for lula dev. +type: docs +--- +## lula dev + +Collection of dev commands to make dev life easier + +### Options + +``` + -h, --help help for dev +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code +* [lula dev get-resources](/cli/cli-commands/lula_dev_get-resources/) - Get Resources from a Lula Validation Manifest +* [lula dev lint](/cli/cli-commands/lula_dev_lint/) - Lint validation files against schema +* [lula dev validate](/cli/cli-commands/lula_dev_validate/) - Run an individual Lula validation. + diff --git a/docs/cli-commands/lula_dev_get-resources.md b/docs/cli-commands/lula_dev_get-resources.md new file mode 100644 index 00000000..6105c50c --- /dev/null +++ b/docs/cli-commands/lula_dev_get-resources.md @@ -0,0 +1,56 @@ +--- +title: lula dev get-resources +description: Lula CLI command reference for lula dev get-resources. +type: docs +--- +## lula dev get-resources + +Get Resources from a Lula Validation Manifest + +### Synopsis + +Get the JSON resources specified in a Lula Validation Manifest + +``` +lula dev get-resources [flags] +``` + +### Examples + +``` + +To get resources from lula validation manifest: + lula dev get-resources -f /path/to/validation.yaml +To get resources from lula validation manifest and write to file: + lula dev get-resources -f /path/to/validation.yaml -o /path/to/output.json +To get resources from lula validation and automatically confirm execution + lula dev get-resources -f /path/to/validation.yaml --confirm-execution +To run validations using stdin: + cat /path/to/validation.yaml | lula dev get-resources +To hang indefinitely for stdin: + lula get-resources -t -1 +To hang for timeout of 5 seconds: + lula get-resources -t 5 + +``` + +### Options + +``` + --confirm-execution confirm execution scripts run as part of getting resources + -h, --help help for get-resources + -f, --input-file string the path to a validation manifest file (default "0") + -o, --output-file string the path to write the resources json + -t, --timeout int the timeout for stdin (in seconds, -1 for no timeout) (default 1) +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula dev](/cli/cli-commands/lula_dev/) - Collection of dev commands to make dev life easier + diff --git a/docs/cli-commands/lula_dev_lint.md b/docs/cli-commands/lula_dev_lint.md new file mode 100644 index 00000000..f17c92bd --- /dev/null +++ b/docs/cli-commands/lula_dev_lint.md @@ -0,0 +1,44 @@ +--- +title: lula dev lint +description: Lula CLI command reference for lula dev lint. +type: docs +--- +## lula dev lint + +Lint validation files against schema + +### Synopsis + +Validate validation files are properly configured against the schema, file paths can be local or URLs (https://) + +``` +lula dev lint [flags] +``` + +### Examples + +``` + +To lint existing validation files: + lula dev lint -f ,, [-r ] + +``` + +### Options + +``` + -h, --help help for lint + -f, --input-files strings the paths to validation files (comma-separated) + -r, --result-file string the path to write the validation result +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula dev](/cli/cli-commands/lula_dev/) - Collection of dev commands to make dev life easier + diff --git a/docs/cli-commands/lula_dev_validate.md b/docs/cli-commands/lula_dev_validate.md new file mode 100644 index 00000000..d6e787a8 --- /dev/null +++ b/docs/cli-commands/lula_dev_validate.md @@ -0,0 +1,58 @@ +--- +title: lula dev validate +description: Lula CLI command reference for lula dev validate. +type: docs +--- +## lula dev validate + +Run an individual Lula validation. + +### Synopsis + +Run an individual Lula validation for quick testing and debugging of a Lula Validation. This command is intended for development purposes only. + +``` +lula dev validate [flags] +``` + +### Examples + +``` + +To run validation from a lula validation manifest: + lula dev validate -f /path/to/validation.yaml +To run validation using a custom resources file: + lula dev validate -f /path/to/validation.yaml -r /path/to/resources.json +To run validation and automatically confirm execution + lula dev validate -f /path/to/validation.yaml --confirm-execution +To run validation from stdin: + cat /path/to/validation.yaml | lula dev validate +To hang indefinitely for stdin: + lula dev validate -t -1 +To hang for timeout of 5 seconds: + lula dev validate -t 5 + +``` + +### Options + +``` + --confirm-execution confirm execution scripts run as part of the validation + -e, --expected-result the expected result of the validation (-e=false for failing result) (default true) + -h, --help help for validate + -f, --input-file string the path to a validation manifest file (default "0") + -o, --output-file string the path to write the validation with results + -r, --resources-file string the path to an optional resources file + -t, --timeout int the timeout for stdin (in seconds, -1 for no timeout) (default 1) +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula dev](/cli/cli-commands/lula_dev/) - Collection of dev commands to make dev life easier + diff --git a/docs/cli-commands/lula_evaluate.md b/docs/cli-commands/lula_evaluate.md new file mode 100644 index 00000000..f16ff17b --- /dev/null +++ b/docs/cli-commands/lula_evaluate.md @@ -0,0 +1,52 @@ +--- +title: lula evaluate +description: Lula CLI command reference for lula evaluate. +type: docs +--- +## lula evaluate + +evaluate two results of a Security Assessment Results + +### Synopsis + +Lula evaluation of Security Assessment Results + +``` +lula evaluate [flags] +``` + +### Examples + +``` + +To evaluate the latest results in two assessment results files: + lula evaluate -f assessment-results-threshold.yaml -f assessment-results-new.yaml + +To evaluate two results (threshold and latest) in a single OSCAL file: + lula evaluate -f assessment-results.yaml + +To target a specific framework for validation: + lula evaluate -f assessment-results.yaml --target critical + + +``` + +### Options + +``` + -h, --help help for evaluate + -f, --input-file strings Path to the file to be evaluated + -s, --summary Print a summary of the evaluation + -t, --target string the specific control implementations or framework to validate against +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code + diff --git a/docs/cli-commands/lula_generate.md b/docs/cli-commands/lula_generate.md new file mode 100644 index 00000000..4aed53aa --- /dev/null +++ b/docs/cli-commands/lula_generate.md @@ -0,0 +1,28 @@ +--- +title: lula generate +description: Lula CLI command reference for lula generate. +type: docs +--- +## lula generate + +Generate a specified compliance artifact template + +### Options + +``` + -h, --help help for generate + -f, --input-file string Path to a manifest file + -o, --output-file string Path and Name to an output file +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code +* [lula generate component](/cli/cli-commands/lula_generate_component/) - Generate a component definition OSCAL template + diff --git a/docs/cli-commands/lula_generate_component.md b/docs/cli-commands/lula_generate_component.md new file mode 100644 index 00000000..d8087d92 --- /dev/null +++ b/docs/cli-commands/lula_generate_component.md @@ -0,0 +1,56 @@ +--- +title: lula generate component +description: Lula CLI command reference for lula generate component. +type: docs +--- +## lula generate component + +Generate a component definition OSCAL template + +``` +lula generate component [flags] +``` + +### Examples + +``` + +To generate a new component-definition template: +lula generate component -c -r control-a,control-b,control-c +- IE lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-2,au-5 + +To Generate and merge with an existing Component Definition: +lula generate component -c -r control-a,control-b,control-c -o existing-component.yaml + +To Generate a component definition with a specific "named" component: +lula generate component -c -r control-a --component "Software X" + +To Generate a component definition with remarks populated from specific control "parts": +lula generate component -c -r control-a --remarks guidance,assessment-objective + +``` + +### Options + +``` + -c, --catalog-source string Catalog source location (local or remote) + --component string Component Title + --framework string Control-Implementation collection that these controls belong to + -h, --help help for component + -p, --profile string Profile source location (local or remote) + --remarks strings Target for remarks population (default = statement) + -r, --requirements strings List of requirements to capture +``` + +### Options inherited from parent commands + +``` + -f, --input-file string Path to a manifest file + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") + -o, --output-file string Path and Name to an output file +``` + +### SEE ALSO + +* [lula generate](/cli/cli-commands/lula_generate/) - Generate a specified compliance artifact template + diff --git a/docs/cli-commands/lula_tools.md b/docs/cli-commands/lula_tools.md new file mode 100644 index 00000000..c1415d2d --- /dev/null +++ b/docs/cli-commands/lula_tools.md @@ -0,0 +1,29 @@ +--- +title: lula tools +description: Lula CLI command reference for lula tools. +type: docs +--- +## lula tools + +Collection of additional commands to make OSCAL easier + +### Options + +``` + -h, --help help for tools +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code +* [lula tools compose](/cli/cli-commands/lula_tools_compose/) - compose an OSCAL component definition +* [lula tools lint](/cli/cli-commands/lula_tools_lint/) - Validate OSCAL against schema +* [lula tools upgrade](/cli/cli-commands/lula_tools_upgrade/) - Upgrade OSCAL document to a new version if possible. +* [lula tools uuidgen](/cli/cli-commands/lula_tools_uuidgen/) - Generate a UUID + diff --git a/docs/cli-commands/lula_tools_compose.md b/docs/cli-commands/lula_tools_compose.md new file mode 100644 index 00000000..d9fefb47 --- /dev/null +++ b/docs/cli-commands/lula_tools_compose.md @@ -0,0 +1,47 @@ +--- +title: lula tools compose +description: Lula CLI command reference for lula tools compose. +type: docs +--- +## lula tools compose + +compose an OSCAL component definition + +### Synopsis + +Lula Composition of an OSCAL component definition. Used to compose remote validations within a component definition in order to resolve any references for portability. + +``` +lula tools compose [flags] +``` + +### Examples + +``` + +To compose an OSCAL Model: + lula tools compose -f ./oscal-component.yaml + +To indicate a specific output file: + lula tools compose -f ./oscal-component.yaml -o composed-oscal-component.yaml + +``` + +### Options + +``` + -h, --help help for compose + -f, --input-file string the path to the target OSCAL component definition + -o, --output-file -composed the path to the output file. If not specified, the output file will be the original filename with -composed appended +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula tools](/cli/cli-commands/lula_tools/) - Collection of additional commands to make OSCAL easier + diff --git a/docs/cli-commands/lula_tools_lint.md b/docs/cli-commands/lula_tools_lint.md new file mode 100644 index 00000000..8511738a --- /dev/null +++ b/docs/cli-commands/lula_tools_lint.md @@ -0,0 +1,45 @@ +--- +title: lula tools lint +description: Lula CLI command reference for lula tools lint. +type: docs +--- +## lula tools lint + +Validate OSCAL against schema + +### Synopsis + +Validate OSCAL documents are properly configured against the OSCAL schema + +``` +lula tools lint [flags] +``` + +### Examples + +``` + +To lint existing OSCAL files: + lula tools lint -f ,, [-r ] + + +``` + +### Options + +``` + -h, --help help for lint + -f, --input-files strings the paths to oscal json schema files (comma-separated) + -r, --result-file string the path to write the validation result +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula tools](/cli/cli-commands/lula_tools/) - Collection of additional commands to make OSCAL easier + diff --git a/docs/cli-commands/lula_tools_upgrade.md b/docs/cli-commands/lula_tools_upgrade.md new file mode 100644 index 00000000..48f291e4 --- /dev/null +++ b/docs/cli-commands/lula_tools_upgrade.md @@ -0,0 +1,46 @@ +--- +title: lula tools upgrade +description: Lula CLI command reference for lula tools upgrade. +type: docs +--- +## lula tools upgrade + +Upgrade OSCAL document to a new version if possible. + +### Synopsis + +Validate an OSCAL document against the OSCAL schema version provided. If the document is valid, upgrade it to the provided OSCAL version. Otherwise, return or write as ValidationError. Yaml formatting handled by gopkg/yaml.v3 and while objects will maintain deep equality, visual representation may be different than the input file. + +``` +lula tools upgrade [flags] +``` + +### Examples + +``` + +To Upgrade an existing OSCAL file: + lula tools upgrade -f -v + +``` + +### Options + +``` + -h, --help help for upgrade + -f, --input-file string the path to a oscal json schema file + -o, --output-file string the path to write the linted oscal json schema file (default is the input file) + -r, --validation-result string the path to write the validation result file + -v, --version string the version of the oscal schema to validate against (default is the latest supported version) (default "1.1.2") +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula tools](/cli/cli-commands/lula_tools/) - Collection of additional commands to make OSCAL easier + diff --git a/docs/cli-commands/lula_tools_uuidgen.md b/docs/cli-commands/lula_tools_uuidgen.md new file mode 100644 index 00000000..355a7a65 --- /dev/null +++ b/docs/cli-commands/lula_tools_uuidgen.md @@ -0,0 +1,45 @@ +--- +title: lula tools uuidgen +description: Lula CLI command reference for lula tools uuidgen. +type: docs +--- +## lula tools uuidgen + +Generate a UUID + +### Synopsis + +Generate a UUID at random or deterministically with a provided string + +``` +lula tools uuidgen [flags] +``` + +### Examples + +``` + +To create a new random UUID: + lula tools uuidgen + +To create a deterministic UUID given some source: + lula tools uuidgen + +``` + +### Options + +``` + -h, --help help for uuidgen +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula tools](/cli/cli-commands/lula_tools/) - Collection of additional commands to make OSCAL easier + diff --git a/docs/cli-commands/lula_validate.md b/docs/cli-commands/lula_validate.md new file mode 100644 index 00000000..bd486329 --- /dev/null +++ b/docs/cli-commands/lula_validate.md @@ -0,0 +1,55 @@ +--- +title: lula validate +description: Lula CLI command reference for lula validate. +type: docs +--- +## lula validate + +validate an OSCAL component definition + +### Synopsis + +Lula Validation of an OSCAL component definition + +``` +lula validate [flags] +``` + +### Examples + +``` + +To validate on a cluster: + lula validate -f ./oscal-component.yaml +To indicate a specific Assessment Results file to create or append to: + lula validate -f ./oscal-component.yaml -o assessment-results.yaml +To target a specific control-implementation source / standard/ framework + lula validate -f ./oscal-component.yaml -t critical +To run validations and automatically confirm execution + lula dev validate -f ./oscal-component.yaml --confirm-execution +To run validations non-interactively (no execution) + lula dev validate -f ./oscal-component.yaml --non-interactive + +``` + +### Options + +``` + --confirm-execution confirm execution scripts run as part of the validation + -h, --help help for validate + -f, --input-file string the path to the target OSCAL component definition + --non-interactive run the command non-interactively + -o, --output-file string the path to write assessment results. Creates a new file or appends to existing files + -t, --target string the specific control implementations or framework to validate against +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code + diff --git a/docs/cli-commands/lula_version.md b/docs/cli-commands/lula_version.md new file mode 100644 index 00000000..92c3e9bf --- /dev/null +++ b/docs/cli-commands/lula_version.md @@ -0,0 +1,42 @@ +--- +title: lula version +description: Lula CLI command reference for lula version. +type: docs +--- +## lula version + +Shows the current version of the Lula binary + +### Synopsis + +Shows the current version of the Lula binary + +``` +lula version [flags] +``` + +### Examples + +``` + +Get the current Lula version: + lula version + +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + -l, --log-level string Log level when running Lula. Valid options are: warn, info, debug, trace (default "info") +``` + +### SEE ALSO + +* [lula](/cli/cli-commands/lula/) - Risk Management as Code + diff --git a/docs/cli-commands/tools/README.md b/docs/cli-commands/tools/README.md deleted file mode 100644 index 623f4e6a..00000000 --- a/docs/cli-commands/tools/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tools - -The `lula tools` or `lula t` commands facilitate usage of additional Lula features and go-oscal capabilities. \ No newline at end of file diff --git a/docs/cli-commands/tools/compose.md b/docs/cli-commands/tools/compose.md deleted file mode 100644 index f81d0196..00000000 --- a/docs/cli-commands/tools/compose.md +++ /dev/null @@ -1,30 +0,0 @@ -# Compose - -The `lula tools compose` command is used to compose an OSCAL component definition. It is used to compose remote validations within a component definition in order to resolve any references for portability. - -## Usage - -```bash -lula tools compose -f -o -``` - -## Options - -- `-f, --input-file`: The path to the target OSCAL component definition. -- `-o, --output-file`: The path to the output file. If not specified, the output file will be the original filename with `-composed` appended (ie. `oscal-component.yaml` will be composed to `oscal-component-composed.yaml`). - -## Examples - -To compose an OSCAL Model: -```bash -lula tools compose -f ./oscal-component.yaml -``` - -To indicate a specific output file: -```bash -lula tools compose -f ./oscal-component.yaml -o composed-oscal-component.yaml -``` - -## Notes - -If the input file does not exist, an error will be returned. The composed OSCAL Component Definition will be written to the specified output file. If no output file is specified, the composed definition will be written to a file with the original filename and `-composed` appended. diff --git a/docs/cli-commands/tools/lint.md b/docs/cli-commands/tools/lint.md deleted file mode 100644 index 51afb7f6..00000000 --- a/docs/cli-commands/tools/lint.md +++ /dev/null @@ -1,32 +0,0 @@ -# Lint Command - -The `lula tools lint` command is used to validate OSCAL files against the OSCAL schema. It can validate both composed and non-composed OSCAL models. -> **Note**: the `lint` command does not compose the OSCAL model. -> If you want to validate a composed OSCAL model, you should use the [`lula tools compose`](./compose/README.md) command first. - -## Usage - -```bash -lula tools lint -f [-r ] -``` - -## Options - -- `-f, --input-files`: The paths to the tar get OSCAL files (comma-separated). -- `-r, --result-file`: The path to the result file. If not specified, the validation results will be printed to the console. - -## Examples - -To lint existing OSCAL files: -```bash -lula tools lint -f ./oscal-component1.yaml,./oscal-component2.yaml -``` - -To specify a result file: -```bash -lula tools lint -f ./oscal-component1.yaml,./oscal-component2.yaml -r validation-results.json -``` - -## Notes - -If no input files are specified, an error will be returned. The validation results will be written to the specified result file. If no result file is specified, the validation results will be printed to the console. If there is at least one validation result that is not valid, the command will exit with a fatal error listing the files that failed linting. \ No newline at end of file diff --git a/docs/cli-commands/tools/uuidgen.md b/docs/cli-commands/tools/uuidgen.md deleted file mode 100644 index 5c84cdc8..00000000 --- a/docs/cli-commands/tools/uuidgen.md +++ /dev/null @@ -1,9 +0,0 @@ -# UUID Gen - -The `uuidgen` command is a helper tool to generate a compliant UUID (universally unique identifier). These UUIDs are relevant across various parameters within the OSCAL models - -## Usage - -```bash -lula tools uuidgen -``` \ No newline at end of file diff --git a/go.mod b/go.mod index 0d2915a7..7947893d 100644 --- a/go.mod +++ b/go.mod @@ -35,6 +35,7 @@ require ( github.com/cespare/xxhash/v2 v2.3.0 // indirect github.com/chai2010/gettext-go v1.0.2 // indirect github.com/containerd/console v1.0.3 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect github.com/daviddengcn/go-colortext v1.0.0 // indirect github.com/distribution/reference v0.5.0 // indirect diff --git a/go.sum b/go.sum index c2e26765..6d378249 100644 --- a/go.sum +++ b/go.sum @@ -48,6 +48,7 @@ github.com/chai2010/gettext-go v1.0.2 h1:1Lwwip6Q2QGsAdl/ZKPCwTe9fe0CjlUbqj5bFNS github.com/chai2010/gettext-go v1.0.2/go.mod h1:y+wnP2cHYaVj19NZhYKAwEMH2CI1gNHeQQ+5AjwawxA= github.com/containerd/console v1.0.3 h1:lIr7SlA5PxZyMV30bDW0MGbiOPXwc63yRuCP0ARubLw= github.com/containerd/console v1.0.3/go.mod h1:7LqA/THxQ86k76b8c/EMSiaJ3h1eZkMkXar0TQ1gf3U= +github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4= github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY= github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4= diff --git a/src/cmd/internal.go b/src/cmd/internal.go new file mode 100644 index 00000000..ff510ebc --- /dev/null +++ b/src/cmd/internal.go @@ -0,0 +1,78 @@ +package cmd + +import ( + "fmt" + "os" + + "path/filepath" + "strings" + + "github.com/defenseunicorns/lula/src/pkg/message" + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +var internalCmd = &cobra.Command{ + Use: "internal", + Hidden: true, + Short: "Internal Commands", +} + +var genCLIDocs = &cobra.Command{ + Use: "gen-cli-docs", + Short: "Generate CLI command documentation", + RunE: func(_ *cobra.Command, _ []string) error { + // Don't include the datestamp in the output + rootCmd.DisableAutoGenTag = true + + // rootCmd.RemoveCommand() + + // remove existing docs + glob, err := filepath.Glob("./docs/cli-commands/lula*.md") + if err != nil { + return err + } + for _, f := range glob { + err := os.Remove(f) + if err != nil { + return err + } + } + + var prependTitle = func(s string) string { + fmt.Println(s) + name := filepath.Base(s) + + // strip .md extension + name = name[:len(name)-3] + + // replace _ with space + title := strings.Replace(name, "_", " ", -1) + + return fmt.Sprintf(`--- +title: %s +description: Lula CLI command reference for %s. +type: docs +--- +`, title, title) + } + + var linkHandler = func(link string) string { + return "/cli/cli-commands/" + link[:len(link)-3] + "/" + } + + err = doc.GenMarkdownTreeCustom(rootCmd, "./docs/cli-commands", prependTitle, linkHandler) + if err != nil { + return err + } + + message.Success("Internal documentation generated") + return nil + }, +} + +func init() { + rootCmd.AddCommand(internalCmd) + + internalCmd.AddCommand(genCLIDocs) +} From 8b807a983fd18822ade151a1b3d893609a64ccf8 Mon Sep 17 00:00:00 2001 From: Brandt Keller Date: Mon, 19 Aug 2024 15:28:44 +0000 Subject: [PATCH 2/3] chore(docs): migrate docs from commands to models --- docs/oscal/assessment-results.md | 47 ++++++ docs/oscal/component-definition.md | 48 +++++- docs/oscal/system-security-plan.md | 244 +++++++++++++++++++++++++++++ 3 files changed, 338 insertions(+), 1 deletion(-) diff --git a/docs/oscal/assessment-results.md b/docs/oscal/assessment-results.md index 0a422ea8..4e23e7e7 100644 --- a/docs/oscal/assessment-results.md +++ b/docs/oscal/assessment-results.md @@ -36,3 +36,50 @@ The primary structure for Lula production and operation of `assessment-results` - Findings are sorted by `target.target-id` in ascending order - Observations are sorted by `collected` time in ascending order - Back Matter Resources are sorted by `title` in ascending order. + +## Compliance Evaluation + +Lula `evaluate` serves as a method for verifying the compliance of a component/system to determine if it is more or less compliant than a previous assessment. This enables OSCAL to serve as a quality gate for compliance evaluation - enabling automation and requiring governance of component or system updates. + +### Threshold + +The term `threshold` is used in Lula processes and workflows to delineate (optimally) a point-in-time where a component/system was most compliant. In identifying this state, a quality gate can be created to require meeting or exceeding said threshold. + +The reason this is crucial is that the previous assessment may not always be the required state. Rather Lula allows capturing provenance for when that state was established and enabling teams to increment Automated Governance workflows. This may be allowing for failures until the assessments have a high level of fidelity in order to parallelize development. + +### Expected Process + +#### No Existing Data + +When no previous assessment exists, the initial assessment is made and stored with `lula validate`. Lula will automatically apply the [threshold](./ns/threshold.md) prop to the assessment result when writing the assessment result to a file that does not contain an existing assessment results artifact. This initial assessment by itself will always pass `lula evaluate` as there is no threshold for evaluation, and the threshold prop with be set to `true`. + +steps: +1. `lula validate -f component.yaml -o assessment-results.yaml` +2. `lula evaluate -f assessment-results.yaml` -> Passes with no Threshold -> Establishes Threshold + +#### Existing Data (Intended Workflow) + +In workflows run manually or with automation (such as CI/CD), there is an expectation that the threshold exists, and evaluate will perform an analysis of the compliance of the system/component against the established threshold. + +steps: +1. `lula validate -f component.yaml -o assessment-results.yaml` +2. `lula evaluate -f assessment-results.yaml` -> Passes or Fails based on threshold + + +### Scenarios for Consideration + +Evaluate will determine which result is the threshold based on the following property: +```yaml +props: + - name: threshold + ns: https://docs.lula.dev/oscal/ns + value: "true/false" +``` + +#### Assessment Results Artifact + +When evaluate is ran with a single assessment results artifact, it is expected that a single threshold with a `true` value exists. This will be identified and ran against the latest result to determine if compliance is less-than-equal (fail), equal (pass), or greater-than-equal (pass). When the comparison results in greater-than-equal, Lula will update the threshold `prop` for the latest result to `true` and set the previous result threshold prop to `false`. + +#### Comparing multiple assessment results artifacts + +In the scenario where multiple assessment results artifacts are evaluated, there may be a multiple threshold results with a `true` value as Lula establishes a default `true` value when writing an assessment results artifact to a new file with no previous results present. In this case, Lula will use the older result as the threshold to determine compliance of the result. \ No newline at end of file diff --git a/docs/oscal/component-definition.md b/docs/oscal/component-definition.md index 2c4b2a83..06b4646b 100644 --- a/docs/oscal/component-definition.md +++ b/docs/oscal/component-definition.md @@ -13,4 +13,50 @@ The primary structure for Lula production and operations of `component-definitio - Components/Capabilities are sorted by `title` in ascending order (Case Sensitive Sorting). - Control Implementations are sorted by `source` in ascending order. - Implemented Requirements are sorted by `control-id` in ascending order. -- Back Matter Resources are sorted by `title` in ascending order (Case Sensitive Sorting). \ No newline at end of file +- Back Matter Resources are sorted by `title` in ascending order (Case Sensitive Sorting). + +## Generation + +Lula can generate OSCAL templates to help with authoring OSCAL artifacts. These generation processes help with initial build and maintenance of OSCAL artifacts and keeps with the vision of modular compliance artifacts that live with the source code. + +To generate a component definition, you need the following context: +- The catalog source `-c` or `--catalog-source`; IE `https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json` +- The controls from the catalog to map to `implemented-requirements` / `-r` or `--requirements`; `ac-1,ac-2,au-5` + +The following command will generate a component definition with the above context: +``` +lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-2,au-5 +``` + +There are optional flags that can be added to the command to generate a component definition: +- The remarks you wish to map from the control parts to the requirement remarks`--remarks`; `assessment-objective,statement,guidance` +- The title of the component `--component`; `Software Title` +- The output file of the component `-o` or `--output`; `oscal-component.yaml` + +### Reproducibility + +The `lula generate` commands are meant to be reproducible and will auto-merge models based on filename. The intent for this generation is to make it easy to update a given model with automation and only inject human intervention as needed. An artifact generated with `lula generate` can be merged with a pre-existing artifact of the same model type. + +For component-definitions, see each individual `control-implementation` props for the `generation` prop. It should look like the following: +```yaml +props: + - name: generation + ns: https://docs.lula.dev/oscal/ns + value: lula generate component --catalog-source https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json --component 'Component Title' --requirements ac-1,ac-3,ac-3.2,ac-4 --remarks assessment-objective +``` + +This `value` should mirror any required inputs in order to reproduce a given control implementation in a component. + +### Existing Data + +The ability to retain data that is put into OSCAL artifacts is of utmost importance to this generation process and also a large feature of continued maintenance of these artifacts. Lula supports the ability to merge newly generated component definition templates into existing component definitions automatically. + +By specifying `--output` or `-o` and providing an existing file - Lula will perform a merge operation that only overwrites specific fields owned by automation. + +Lula performs a match on the component title and the provided catalog source to determine placement and merge of the new implemented requirements. This can be used to updated exiting items or as a method to generation of a single artifacts that contains the data for many components or many control implementations. + +## Example + +```bash +./bin/lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-3,ac-3.2,ac-4 -o oscal-component.yaml --remarks assessment-objective +``` \ No newline at end of file diff --git a/docs/oscal/system-security-plan.md b/docs/oscal/system-security-plan.md index 6fad9af0..c85a37fb 100644 --- a/docs/oscal/system-security-plan.md +++ b/docs/oscal/system-security-plan.md @@ -36,3 +36,247 @@ Contains any `leveraged-authorizations`, if used, all `components` used to build ## Control Implementation Contains all of the compliance controls the system must adhere to as outlined within the `profile`. Each `implemented-requirement` is listed detailing the control and the information of how the system meets the control on a `by-component` instance. The component will outline all `export`, `inherited`, and `satisfied` indications for each control the component represents. + +## System Security Plan Generate + +To generate a system security plan, you need the following context: +- The component definition `--component` +- The profile source `--profile` or catalog source `--catalog`; IE `https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_HIGH-baseline-resolved-profile_catalog.json` + +The following command will generate a system security plan with the above context: + +```bash + +lula generate system-security-plan --component .src/test/unit/valid-component.yaml --catalog https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_HIGH-baseline-resolved-profile_catalog.json + +``` + +There are optional flags that can be added to the command to generate a system security plan: + +- The output file of the component `-o` or `--output`; `oscal-system-security-plan.yaml` + +## System Security Plan Generate Context + +The `system-security-plan` can be generated using the upstream catalog and/or profile in conjunction with the `component-definition`. There are net new fields that are apart of the `system-security-plan` that are not within the `component-definition` or catalog/profile that currently do not make sense to add as props. Those items are under the section `Elements in SSP Not in Component Definition`. There are items that are not in the `system-security-plan` but also not in the `component-definition` that currently do make sense to create as props. Those items are under the section `Elements NOT in Component Definition that need added for SSP Generate`. Lastly as a note there are items within the `component-definition` that are not used in the `system-security-plan` that can be found under the section Elements NOT in `Component Definition that need added for SSP Generate`. + +The items in `Elements in SSP Not in Component Definition` need further context to fill in the missing elements as well as establish data across OSCAL models. Some examples of the data fields are within the `metadata` fields such as `responsible-roles`, `responsible-parties`, and `parties` that can be added to the `system-security-plan` that do not directly map from the `component-definition` field. Additional context can be added through common OSCAL fields such as `props`, `links`, and `remarks`. + +### Further Research Fields + +The following fields need further research to further enhance generating an SSP. + +- `inherited` +- `export` + +### Elements in Component Definition Not in SSP + +- `import-component-definitions` +- `capabilities` + - `uuid` + - `name` + - `description` + - `props` + - `links` + - `incorporates-components` + - `component-uuid` + - `description` + +### Elements in SSP Not in Component Definition + +- `system-characteristics` + - `system-ids` + - `identifier-type` + - `id` + - `system-name` + - `system-name-short` + - `description` + - `security-sensitivity-level` + - `system-information` + - `information-types` + - `id` + - `title` + - `description` + - `security-objective-confidentiality` + - `security-objective-integrity` + - `security-objective-availability` + - `security-impact-level` + - `security-objective-confidentiality` + - `security-objective-integrity` + - `security-objective-availability` + - `status` + - `state` + - `remarks` + - `authorized-boundary` + - `description` + - `props` + - `links` + - `diagrams` + - `uuid` + - `description` + - `props` + - `links` + - `caption` + - `remarks` + - `remarks` + - `network-architecture` + - `description` + - `props` + - `links` + - `diagrams` + - `uuid` + - `description` + - `props` + - `links` + - `caption` + - `remarks` + - `remarks` + - `data-flow` + - `description` + - `props` + - `links` + - `diagrams` + - `uuid` + - `description` + - `props` + - `links` + - `caption` + - `remarks` + - `remarks` + - `props` + - `links` + - `remarks` +- `system-implementation` + - `users` + - `uuid` + - `title` + - `short-name` + - `description` + - `props` + - `links` + - `role-ids` + - `authorized-privileges` + - `title` + - `description` + - `functions-performed` + - `remarks` + - `leveraged-authorizations` + - `uuid` + - `title` + - `props` + - `links` + - `party-uuid` + - `date-authorized` + - `remarks` + - `inventory-items` + - `uuid` + - `description` + - `props` + - `links` + - `remarks` +- `control-implementation` + - `implemented-requirements` + - `statements` + - `satisfied` + - `uuid` + - `responsibility` + - `description` + - `props` + - `links` + - `responsible-roles` + - `role-id` + - `props` + - `links` + - `party-uuid` + - `remarks` + - `role-ids` + - `by-components` + - `satisfied` + - `uuid` + - `responsibility` + - `description` + - `props` + - `links` + - `responsible-roles` + - `role-id` + - `props` + - `links` + - `party-uuid` + - `remarks` + - `role-ids` + +### Elements NOT in Component Definition that need added for SSP Generate + +- `control-implementation` + - `implemented-requirements` + - `by-components` + - `implementation-status` + - `state` + - `remarks` + - `statements` + - `by-components` + - `implementation-status` + - `state` + - `remarks` + +### Component Definition to SSP Transferable Fields + +### **NOTE:** repetitive children elements have been truncated to reduce bloat + +- `metadata` + - `title` + - `published` + - `last-modified` + - `version` + - `oscal-version` + - `revisions` + - `document-ids` + - `props` + - `links` + - `roles` + - `locations` + - `actions` +- `control-implementation` + - `description` + - `set-parameters` + - `param-id` + - `values` + - `remarks` + - `implemented-requirements` + - `uuid` + - `control-id` + - `props` + - `links` + - `set-parameters` + - `param-id` + - `values` + - `remarks` + - `statements` + - `statement-id` + - `props` + - `responsible-roles` + - `links` + - `by-components` + - `by-components` + - `component-uuid` + - `description` + - `props` + - `links` + - `set-parameters` + - `param-id` + - `values` + - `remarks` + - `system-implementation` (Contains Fields from Component Definition) + - `components` + - `uuid` + - `type` + - `title` + - `description` + - `purpose` + - `props` + - `links` + - `status` + - `protocols` + - `implemented-components` + - `component-uuid` + - `props` + - `links` From 8610d98cf198e3aa6887e4d503a876bc0ac467f8 Mon Sep 17 00:00:00 2001 From: Brandt Keller Date: Thu, 22 Aug 2024 23:04:37 +0000 Subject: [PATCH 3/3] chore(docs): fix review comments for content --- docs/oscal/assessment-results.md | 2 +- docs/oscal/component-definition.md | 5 +---- docs/oscal/system-security-plan.md | 10 ++++++---- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/oscal/assessment-results.md b/docs/oscal/assessment-results.md index 4e23e7e7..1382977f 100644 --- a/docs/oscal/assessment-results.md +++ b/docs/oscal/assessment-results.md @@ -45,7 +45,7 @@ Lula `evaluate` serves as a method for verifying the compliance of a component/s The term `threshold` is used in Lula processes and workflows to delineate (optimally) a point-in-time where a component/system was most compliant. In identifying this state, a quality gate can be created to require meeting or exceeding said threshold. -The reason this is crucial is that the previous assessment may not always be the required state. Rather Lula allows capturing provenance for when that state was established and enabling teams to increment Automated Governance workflows. This may be allowing for failures until the assessments have a high level of fidelity in order to parallelize development. +The reason this is crucial is that the previous assessment may not always be the required state. Rather Lula allows capturing provenance for when that state was established and enabling teams to increment Automated Governance workflows. This may be allowing for failures until the assessments have a high level of fidelity in order to parallelize development. ### Expected Process diff --git a/docs/oscal/component-definition.md b/docs/oscal/component-definition.md index 06b4646b..526ef70f 100644 --- a/docs/oscal/component-definition.md +++ b/docs/oscal/component-definition.md @@ -28,10 +28,7 @@ The following command will generate a component definition with the above contex lula generate component -c https://raw.githubusercontent.com/usnistgov/oscal-content/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -r ac-1,ac-2,au-5 ``` -There are optional flags that can be added to the command to generate a component definition: -- The remarks you wish to map from the control parts to the requirement remarks`--remarks`; `assessment-objective,statement,guidance` -- The title of the component `--component`; `Software Title` -- The output file of the component `-o` or `--output`; `oscal-component.yaml` +There are optional flags that can be added to the command to generate a component definition - see [lula generate component](../cli-commands/lula_generate_component.md) for details. ### Reproducibility diff --git a/docs/oscal/system-security-plan.md b/docs/oscal/system-security-plan.md index c85a37fb..7203c314 100644 --- a/docs/oscal/system-security-plan.md +++ b/docs/oscal/system-security-plan.md @@ -37,13 +37,15 @@ Contains any `leveraged-authorizations`, if used, all `components` used to build Contains all of the compliance controls the system must adhere to as outlined within the `profile`. Each `implemented-requirement` is listed detailing the control and the information of how the system meets the control on a `by-component` instance. The component will outline all `export`, `inherited`, and `satisfied` indications for each control the component represents. -## System Security Plan Generate +## System Security Plan Generation + +**NOTE:** This command is in an active research phase. To generate a system security plan, you need the following context: -- The component definition `--component` -- The profile source `--profile` or catalog source `--catalog`; IE `https://raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_HIGH-baseline-resolved-profile_catalog.json` +- The component definition +- The profile source or catalog source -The following command will generate a system security plan with the above context: +The following command could generate a system security plan with the above context: ```bash