Merge pull request #75 from GSA-TTS/oscal-component-definition

Document cg-egress-proxy controls within an OSCAL component definition

.github/actions/trestle-cmd/action.yml

@@ -0,0 +1,16 @@
+name: "Run a docker-trestle command"
+description: "Sets up workspace for running a single command in docker-trestle"
+inputs:
+  tag:
+    description: docker-trestle tag to use.
+    required: false
+    default: 20240930
+  cmd:
+    description: Command to run within docker-trestle
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Run cmd
+      shell: bash
+      run: docker run -u "$(id -u):$(id -g)" -v $GITHUB_WORKSPACE/docs/compliance:/app/docs:rw ghcr.io/gsa-tts/trestle:${{ inputs.tag }} ${{ inputs.cmd }}

.github/workflows/validate-oscal.yml

@@ -0,0 +1,49 @@
+name: Validate OSCAL Assembly
+
+on: [pull_request]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  validate_cd:
+    name: Validate component definition format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate Component
+        uses: ./.github/actions/trestle-cmd
+        with:
+          cmd: trestle validate -f component-definitions/cg-egress-proxy/component-definition.json
+
+  check_cd:
+    name: Check assembly is current
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check assembly
+        uses: ./.github/actions/trestle-cmd
+        with:
+          cmd: bin/assemble-cgep-json
+
+      - name: Check no changes exist
+        run: git diff --quiet
+
+      - name: Comment on pull request
+        if: failure()
+        uses: actions/github-script@v4
+        with:
+          script: |
+            const output = `OSCAL assembly detected changes that aren't checked in.
+
+            Run \`bin/assemble-cgep-json\` within trestle to ensure markdown changes are reflected in the CD`;
+
+            github.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: output
+            });

.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
 /todo.txt
 *.acl
+**/.trestle/cache/
+**/.trestle/_trash/

README.md

@@ -20,6 +20,7 @@ Creators of of US federal systems are [required](https://csrc.nist.gov/projects/
 
 Deploying this egress proxy in front of your cloud.gov application will help you meet this requirement!
 
+See <docs/compliance/README.md> for information on the OSCAL documentation for this repo.
 <!-- assorted keywords: nist rmf 800-53 fisma fedramp sc-7 gsa boundary egress -->
 </details>
 

docs/compliance/README.md

@@ -0,0 +1,32 @@
+# Compliance artifacts for cg-egress-proxy
+
+[cg-egress-proxy.json](./cg-egress-proxy.json) is an OSCAL Component Definition for cg-egress-proxy. You can import it
+into your OSCAL SSP using [docker-trestle](https://github.com/GSA-TTS/docker-trestle)
+
+Inside the docker-trestle CLI:
+
+```bash
+copy-component -n cg-egress-proxy -u https://raw.githubusercontent.com/GSA-TTS/cg-egress-proxy/refs/heads/main/docs/compliance/component-definitions/cg-egress-proxy/component-definition.json
+```
+
+## Development of OSCAL in this directory
+
+To update the OSCAL component definition, utilize `docker-trestle` by running:
+
+`docker run -it --rm -e SKIP_TRESTLE_CONFIG=true -v (pwd):/app/docs ghcr.io/gsa-tts/trestle bash`
+
+from within the `docs/compliance` directory.
+
+### Directory structure
+
+#### bin
+
+Helper scripts to be called from within the `docker-trestle` CLI for transforming the CD into markdown and back again.
+
+#### component-definitions
+
+The OSCAL json component definition files to be distributed.
+
+#### control-statements
+
+The markdown files for updating implementation statements

docs/compliance/bin/assemble-cgep-json

@@ -0,0 +1,3 @@
+#! /usr/bin/env bash
+
+trestle author component-assemble -o cg-egress-proxy -m control-statements "$@"

docs/compliance/bin/generate-cgep-markdown

@@ -0,0 +1,3 @@
+#! /usr/bin/env bash
+
+trestle author component-generate -n cg-egress-proxy -o control-statements -fo "$@"

docs/compliance/component-definitions/cg-egress-proxy/component-definition.json

@@ -0,0 +1,68 @@
+{
+  "component-definition": {
+    "uuid": "d2f3e1b7-363a-4c8a-afb9-7cee1e825bdc",
+    "metadata": {
+      "title": "cg-egress-proxy Egress Proxy Component Definition.",
+      "last-modified": "2024-10-03T13:28:05.931086+00:00",
+      "version": "0.0.1",
+      "oscal-version": "1.1.2"
+    },
+    "components": [
+      {
+        "uuid": "1acb8ab7-4191-46c6-b79f-659a2f195b5a",
+        "type": "software",
+        "title": "cg-egress-proxy",
+        "description": "The cg-egress-proxy caddy server with forward_proxy configured",
+        "props": [
+          {
+            "name": "Rule_Id",
+            "value": "prod-space-restricted",
+            "remarks": "rule_prod_space_restricted"
+          },
+          {
+            "name": "Rule_Description",
+            "value": "The production space where the system app is running must not have the public-networks-egress ASG applied to it",
+            "remarks": "rule_prod_space_restricted"
+          }
+        ],
+        "control-implementations": [
+          {
+            "uuid": "eba1125b-5fd7-46c3-8edc-bf22d67d98cf",
+            "source": "https://raw.githubusercontent.com/usnistgov/oscal-content/refs/tags/v1.3.0/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json",
+            "description": "Controls implemented via use of the cg-egress-proxy outbound connection proxy",
+            "implemented-requirements": [
+              {
+                "uuid": "09de7f16-6339-4daa-b09a-333c5e33185c",
+                "control-id": "sc-7",
+                "description": "",
+                "props": [
+                  {
+                    "name": "implementation-status",
+                    "value": "partial"
+                  }
+                ],
+                "statements": [
+                  {
+                    "statement-id": "sc-7_smt.c",
+                    "uuid": "b56aa629-2452-4052-a5c0-7d245a8122a2",
+                    "description": "eg-egress-proxy provides a control point for allowing network traffic to specific hostnames or IP addresses. Outbound connections are compared to the following list in order:\n\n1. A `deny_file` list of hostnames and/or IP addresses to deny connections to.\n1. An `allow_file` list of hostnames and/or IP addresses to allow connections to.\n1. A `deny all` rule to deny all connections that did not match one of the first two rules.\n\nThe connection is allowed or denied based on the first matching rule.",
+                    "props": [
+                      {
+                        "name": "Rule_Id",
+                        "value": "prod-space-restricted"
+                      },
+                      {
+                        "name": "implementation-status",
+                        "value": "implemented"
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

docs/compliance/control-statements/cg-egress-proxy/source_001/sc/sc-7.md

@@ -0,0 +1,75 @@
+---
+x-trestle-comp-def-rules:
+  cg-egress-proxy:
+    - name: prod-space-restricted
+      description: The production space where the system app is running must not have
+        the public-networks-egress ASG applied to it
+x-trestle-param-values:
+  sc-07_odp:
+x-trestle-global:
+  profile:
+    title: Electronic Version of NIST SP 800-53 Rev 5.1.1 Controls and SP 800-53A
+      Rev 5.1.1 Assessment Procedures
+    href: 
+      https://raw.githubusercontent.com/usnistgov/oscal-content/refs/tags/v1.3.0/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json
+  sort-id: sc-07
+---
+
+# sc-7 - \[System and Communications Protection\] Boundary Protection
+
+## Control Statement
+
+- \[a.\] Monitor and control communications at the external managed interfaces to the system and at key internal managed interfaces within the system;
+
+- \[b.\] Implement subnetworks for publicly accessible system components that are {{ insert: param, sc-07_odp }} separated from internal organizational networks; and
+
+- \[c.\] Connect to external networks or systems only through managed interfaces consisting of boundary protection devices arranged in accordance with an organizational security and privacy architecture.
+
+## Control Assessment Objective
+
+- \[SC-07a.\]
+
+  - \[SC-07a.[01]\] communications at external managed interfaces to the system are monitored;
+  - \[SC-07a.[02]\] communications at external managed interfaces to the system are controlled;
+  - \[SC-07a.[03]\] communications at key internal managed interfaces within the system are monitored;
+  - \[SC-07a.[04]\] communications at key internal managed interfaces within the system are controlled;
+
+- \[SC-07b.\] subnetworks for publicly accessible system components are {{ insert: param, sc-07_odp }} separated from internal organizational networks;
+
+- \[SC-07c.\] external networks or systems are only connected to through managed interfaces consisting of boundary protection devices arranged in accordance with an organizational security and privacy architecture.
+
+## Control guidance
+
+Managed interfaces include gateways, routers, firewalls, guards, network-based malicious code analysis, virtualization systems, or encrypted tunnels implemented within a security architecture. Subnetworks that are physically or logically separated from internal networks are referred to as demilitarized zones or DMZs. Restricting or prohibiting interfaces within organizational systems includes restricting external web traffic to designated web servers within managed interfaces, prohibiting external traffic that appears to be spoofing internal addresses, and prohibiting internal traffic that appears to be spoofing external addresses. [SP 800-189](#f5edfe51-d1f2-422e-9b27-5d0e90b49c72) provides additional information on source address validation techniques to prevent ingress and egress of traffic with spoofed addresses. Commercial telecommunications services are provided by network components and consolidated management systems shared by customers. These services may also include third party-provided access lines and other service elements. Such services may represent sources of increased risk despite contract security provisions. Boundary protection may be implemented as a common control for all or part of an organizational network such that the boundary to be protected is greater than a system-specific boundary (i.e., an authorization boundary).
+
+______________________________________________________________________
+
+## What is the solution and how is it implemented?
+
+<!-- For implementation status enter one of: implemented, partial, planned, alternative, not-applicable -->
+
+<!-- Note that the list of rules under ### Rules: is read-only and changes will not be captured after assembly to JSON -->
+
+<!-- Add control implementation description here for control: sc-7 -->
+
+### Implementation Status: partial
+
+______________________________________________________________________
+
+## Implementation for part c.
+
+eg-egress-proxy provides a control point for allowing network traffic to specific hostnames or IP addresses. Outbound connections are compared to the following list in order:
+
+1. A `deny_file` list of hostnames and/or IP addresses to deny connections to.
+1. An `allow_file` list of hostnames and/or IP addresses to allow connections to.
+1. A `deny all` rule to deny all connections that did not match one of the first two rules.
+
+The connection is allowed or denied based on the first matching rule.
+
+### Rules:
+
+  - prod-space-restricted
+
+### Implementation Status: implemented
+
+______________________________________________________________________