diff --git a/.gitignore b/.gitignore index 7f2256c9..172ea8bf 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,161 @@ node_modules/ /.vs client/.angular client/.nx -/docs /client/src/development.html /api/.env + + +### JupyterNotebooks ### +# gitignore template for Jupyter Notebooks +# website: http://jupyter.org/ + +.ipynb_checkpoints +*/.ipynb_checkpoints/* + +# IPython +profile_default/ +ipython_config.py + +# Remove previous ipynb_checkpoints +# git rm -r .ipynb_checkpoints/ + +### Python ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook + +# IPython + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# End of https://www.toptal.com/developers/gitignore/api/python,jupyternotebooks +/.vs +*/.vs \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..d555fe36 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt diff --git a/client/src/app/common/utils/poam-export.service.ts b/client/src/app/common/utils/poam-export.service.ts index 35d454c5..2687fe86 100644 --- a/client/src/app/common/utils/poam-export.service.ts +++ b/client/src/app/common/utils/poam-export.service.ts @@ -197,7 +197,7 @@ export class PoamExportService { U: '', V: 'likelihood', W: '', - X: '', + X: 'impactDescription', Y: 'residualRisk', Z: '', AA: 'adjSeverity', @@ -247,8 +247,8 @@ export class PoamExportService { vulnerabilitySource: (value: any, poam: Poam, _columnKey: string): any => { if (value === 'STIG') { return poam.vulnerabilityTitle; - } else if (value === 'Task Order') { - return `Task Order #: ${poam.taskOrderNumber}`; + } else if (value === 'Assured Compliance Assessment Solution (ACAS) Nessus Scanner') { + return poam.vulnerabilityTitle; } else { return poam.vulnerabilitySource; } diff --git a/client/src/app/pages/asset-processing/asset-processing.component.html b/client/src/app/pages/asset-processing/asset-processing.component.html index 6917cdf1..7119a4b8 100644 --- a/client/src/app/pages/asset-processing/asset-processing.component.html +++ b/client/src/app/pages/asset-processing/asset-processing.component.html @@ -118,7 +118,6 @@ [(ngModel)]="asset.assetId" placeholder="Select Asset to Modify..." (onChange)="setAsset($event.value.assetId)" - appendTo="body" styleClass="mt-2 w-full" required [disabled]="accessLevel < 2"> @@ -137,7 +136,11 @@ - + diff --git a/client/src/app/pages/asset-processing/asset/asset.component.html b/client/src/app/pages/asset-processing/asset/asset.component.html index 4fa8f99d..1244a70f 100644 --- a/client/src/app/pages/asset-processing/asset/asset.component.html +++ b/client/src/app/pages/asset-processing/asset/asset.component.html @@ -9,96 +9,92 @@ -->
-
-
- -
- -
+
+
+ +
+
-
-
- -
- -
-
-
-
- -
- -
-
-
-
- -
- -
-
-
-
- -
- -
-
-
-
- -
- -
+
+
+
+ +
+
-
-
- - - - - - - Label - - - - - - - - - {{label.labelName}} - - - - - - - - No Data to Display - - - +
+
+
+ +
+
-
-
- +
+
+ +
+
-
- +
+
+
+ +
+
+
+
+ + + + + + + Label + + + + + + + + + {{label.labelName}} + + + + + + + + No Data to Display + + + +
+
+
+
+ +
+
+ +
+
diff --git a/client/src/app/pages/asset-processing/asset/asset.component.ts b/client/src/app/pages/asset-processing/asset/asset.component.ts index 5749af23..6ed5eae2 100644 --- a/client/src/app/pages/asset-processing/asset/asset.component.ts +++ b/client/src/app/pages/asset-processing/asset/asset.component.ts @@ -38,14 +38,10 @@ export class AssetComponent implements OnInit, OnChanges, OnDestroy { labelList: any; clonedLabels: { [s: string]: any } = {}; - collectionList: any; - collection: any; assetLabels: any[] = []; data: any = []; - tcollectionName: string = ''; selectedCollection: any; private subscriptions = new Subscription(); - collectionOptions: any[] = []; labelOptions: any[] = []; displayInvalidDataDialog: boolean = false; invalidDataMessage: string = ''; @@ -71,7 +67,6 @@ export class AssetComponent implements OnInit, OnChanges, OnDestroy { } async getData() { - await this.getCollectionData(); if (!this.selectedCollection) { this.subscriptions.add( this.sharedService.selectedCollection.subscribe((collectionId) => { @@ -90,30 +85,9 @@ export class AssetComponent implements OnInit, OnChanges, OnDestroy { await this.assetService.getLabels(this.selectedCollection) ).subscribe((labels: any) => { this.labelList = labels || []; - this.labelOptions = this.transformToDropdownOptions( - labels, - 'labelName', - 'labelId', - ); }); } - async getCollectionData() { - this.subs.sink = (await this.collectionService.getCollections()).subscribe( - (collections: any) => { - this.collectionList = collections || []; - this.collectionOptions = this.transformToDropdownOptions( - collections, - 'collectionName', - 'collectionId', - ); - if (this.asset.collectionId) { - this.setCollection(this.asset.collectionId); - } - }, - ); - } - async getAssetLabels() { if (!this.asset?.assetId) { console.error('Asset or assetId is not available'); @@ -142,25 +116,6 @@ export class AssetComponent implements OnInit, OnChanges, OnDestroy { })); } - setCollection(collectionId: any) { - this.collection = null; - this.tcollectionName = ''; - - const selectedData = this.collectionList - ? this.collectionList.find( - (collection: { collectionId: any }) => - collection.collectionId === collectionId, - ) - : null; - - if (selectedData) { - this.collection = selectedData; - this.tcollectionName = this.collection.collectionName; - } else { - console.error(`Collection with ID ${collectionId} not found.`); - } - } - addNewRow() { const newLabel = { assetId: +this.asset.assetId, @@ -168,7 +123,7 @@ export class AssetComponent implements OnInit, OnChanges, OnDestroy { labelName: null, isNew: true, }; - this.assetLabels = [...this.assetLabels, newLabel]; + this.assetLabels = [newLabel, ...this.assetLabels]; } onLabelChange(label: any, rowIndex: number) { diff --git a/client/src/app/pages/import-processing/tenable-import/tenableVulnerabilities.component.html b/client/src/app/pages/import-processing/tenable-import/tenableVulnerabilities.component.html index 3fd89d9a..60abc60e 100644 --- a/client/src/app/pages/import-processing/tenable-import/tenableVulnerabilities.component.html +++ b/client/src/app/pages/import-processing/tenable-import/tenableVulnerabilities.component.html @@ -180,7 +180,7 @@ styleClass="p-datatable-sm p-datatable-gridlines-hidden"> - + {{col.header}} { const processedPoams = []; - const vulnerabilityIds = [...new Set(poams.map((poam) => poam.vulnerabilityId))]; + const vulnerabilityIds = [...new Set( + poams + .filter(poam => poam.vulnerabilitySource === "Assured Compliance Assessment Solution (ACAS) Nessus Scanner") + .map(poam => poam.vulnerabilityId) + )]; const analysisParams = { query: { @@ -291,7 +295,7 @@ export class PoamGridComponent implements OnInit, OnChanges, OnDestroy { const processedPoams = []; for (const poam of poams) { - if (poam.vulnerabilityId && poam.stigBenchmarkId) { + if (poam.vulnerabilityId && poam.stigBenchmarkId && poam.vulnerabilitySource === "STIG") { try { let findings: any[]; if (this.findingsCache.has(poam.stigBenchmarkId)) { diff --git a/client/src/app/pages/poam-processing/poam-manage/poam-manage.component.scss b/client/src/app/pages/poam-processing/poam-manage/poam-manage.component.scss index 414bb58b..47cd0735 100644 --- a/client/src/app/pages/poam-processing/poam-manage/poam-manage.component.scss +++ b/client/src/app/pages/poam-processing/poam-manage/poam-manage.component.scss @@ -3,6 +3,7 @@ display: block; height: 100%; min-height: 16rem; + width: 100%; ::ng-deep { .total-value, @@ -10,6 +11,47 @@ .item-percent { line-height: 1.5; } + + .advanced-pie-legend { + width: 100%; + + .legend-items-container { + width: 100%; + + .legend-items { + display: flex; + flex-wrap: wrap; + width: 100%; + gap: 0.5rem; + + .legend-item { + flex: 1 1 auto; + min-width: 0; + width: fit-content; + + .item-label { + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + } + } + } + } + } + } +} + +.poam-severity-advanced-pie { + ::ng-deep .advanced-pie-legend { + .legend-items-container .legend-items { + flex-wrap: nowrap !important; + justify-content: center; + + .legend-item { + flex: 1; + min-width: 0; + } + } } } @@ -21,13 +63,11 @@ } .legend-items-container .legend-items { - display: flex; - flex-wrap: wrap; justify-content: flex-end; margin-top: 0.10rem; .legend-item { - flex: 1 1 calc(50% - 0.5rem); + flex: 1 1 auto; margin-bottom: 0.5rem; @media screen and (min-width: 768px) { @@ -46,27 +86,25 @@ &.p-card .p-card-body { padding: 0 !important; } - .p-tabview { .p-tabview-panels, .p-tabview-panel { padding: 0 !important; } - + .p-tabview-nav { padding-left: 0.25rem; padding-right: 0.25rem; } } - + cpat-poam-assigned-grid { width: 100% !important; display: block !important; - + .p-datatable { width: 100% !important; padding: 0; - .p-datatable-wrapper { border-left: 0 !important; border-right: 0 !important; @@ -76,9 +114,31 @@ } } +@media screen and (max-width: 992px) { + .poam-severity-advanced-pie { + ::ng-deep .advanced-pie-legend .legend-items-container .legend-items { + gap: 0.375rem; + } + } +} + @media screen and (max-width: 768px) { .grid > .col-12 { padding-left: 0 !important; padding-right: 0 !important; } + .poam-severity-advanced-pie { + ::ng-deep .advanced-pie-legend .legend-items-container .legend-items { + gap: 0.25rem; + } + } +} + +@media screen and (max-width: 576px) { + .poam-severity-advanced-pie { + ::ng-deep .advanced-pie-legend .legend-items-container .legend-items { + gap: 0.125rem; + } + } } + diff --git a/client/src/assets/icons/poam-component-documentation.md b/client/src/assets/icons/poam-component-documentation.md new file mode 100644 index 00000000..76e1a67a --- /dev/null +++ b/client/src/assets/icons/poam-component-documentation.md @@ -0,0 +1,207 @@ +######################################## +POAM Component Documentation +######################################## + +Technical Overview +================= + +Purpose +------- +The POAM (Plan of Action & Milestones) component is a comprehensive interface for managing security vulnerability tracking and remediation planning. It provides capabilities for creating, editing, and managing POAMs through both manual entry and automated integration with security tools. + +Architecture +----------- +The component is built using Angular and implements the following key architectural patterns: + +* **Component Pattern**: Uses ``@Component`` decorator with separate template and styling files +* **Reactive Forms**: Implements form handling with validation and state management +* **Service Integration**: Integrates with multiple services for data management +* **Stepper Interface**: Organizes content into logical sections using PrimeNG Stepper + +Key Dependencies +-------------- +* **Angular Core Components**: ``ChangeDetectorRef``, ``Component``, ``OnDestroy``, ``OnInit``, ``ViewChild`` +* **Angular Router**: For navigation and route parameter handling +* **PrimeNG Components**: + - ``Table`` + - ``Menu`` + - ``Calendar`` + - ``Dropdown`` + - ``Stepper`` + - ``Dialog`` + - ``ConfirmDialog`` +* **Date Handling**: ``date-fns`` library for date manipulation +* **RxJS**: For reactive programming patterns + +POAM Creation Methods +==================== + +Manual POAM Entry +---------------- +.. note:: Manual entry is not the recommended approach. Use automated integration when possible. + +Workflow: +1. Navigate to POAM creation interface +2. Select "ADDPOAM" mode +3. Complete required fields: + - Description + - A&A Package + - Vulnerability Source + - Raw Severity + - Scheduled Completion Date + +STIG Manager Integration +----------------------- +The preferred method for STIG-related vulnerabilities. + +**Automation Process**: +1. Integration automatically populates: + - Vulnerability Source (set to "STIG") + - STIG Title + - Vulnerability ID + - Description + - Raw Severity + - Scheduled Completion Date (calculated based on severity) + +**Field Automation**: +.. code-block:: typescript + + createNewSTIGManagerPoam() { + // Auto-population logic + this.poam = { + vulnerabilitySource: 'STIG', + description: this.stateData.description, + rawSeverity: this.stateData.severity, + // ... other fields + }; + } + +Tenable Integration +------------------ +Recommended for ACAS scanner findings. + +**Automation Process**: +1. Pulls vulnerability data from Tenable +2. Auto-populates: + - Plugin ID + - Vulnerability Description + - IAVM Information (if available) + - Raw Severity (mapped from Tenable severity) + +**Field Mapping**: +.. code-block:: typescript + + mapTenableSeverity(severity: string) { + switch (severity) { + case '4': return 'CAT I - Critical'; + case '3': return 'CAT I - High'; + // ... other mappings + } + } + +Field Documentation +================= + +Core Fields +---------- + +Description +~~~~~~~~~~ +* **Purpose**: Describes the identified vulnerability +* **Source**: Assessment procedure or technical finding +* **Validation**: Required field, max 10000 characters +* **Automation**: Auto-populated from STIG/Tenable when available + +Status +~~~~~~ +* **Options**: + - Draft (default) + - Submitted + - Pending CAT-I Approval + - Approved + - Rejected + - Closed + - Expired +* **Access Control**: Requires Level 2 access to modify + +Severity Ratings +-------------- + +Raw Severity +~~~~~~~~~~ +* **Purpose**: Initial vulnerability severity +* **Options**: + - CAT I - Critical + - CAT I - High + - CAT II - Medium + - CAT III - Low + - CAT III - Informational +* **Automation**: Mapped from source system ratings + +Adjusted Severity +~~~~~~~~~~~~~~~ +* **Purpose**: Modified severity after mitigations +* **Validation**: Requires mitigation documentation if different from raw severity +* **Access**: Requires Level 3 access to modify + +Dates and Timelines +----------------- + +Scheduled Completion Date +~~~~~~~~~~~~~~~~~~~~~~~ +* **Required**: Yes +* **Calculation**: Based on severity level + - CAT I: 30 days + - CAT II: 180 days + - CAT III: 365 days +* **Validation**: Cannot be empty + +IAV Comply By Date +~~~~~~~~~~~~~~~~ +* **Required**: Only if IAVM number is provided +* **Format**: YYYY-MM-DD +* **Validation**: Must be valid date + +Teams and Approvers +----------------- + +Assigned Teams +~~~~~~~~~~~~ +* **Management**: Add/remove via team selection +* **Validation**: At least one team required +* **Access**: Level 2 required for modification + +Approvers +~~~~~~~~ +* **Default**: Auto-populated with collection approvers +* **Status Options**: + - Not Reviewed + - Approved + - Rejected +* **Access**: Level 3 required for approval actions + +Milestones +--------- +* **Required**: Minimum 1 milestone before submission +* **Fields**: + - Milestone Comments (min 15 characters) + - Due Date + - Status (Pending/Complete) + - Team Assignment +* **Validation**: Due dates must not exceed completion date + +.. warning:: + Milestone dates cannot exceed the scheduled completion date unless an extension has been approved. + +Access Control Levels +=================== + +The component implements five access levels: + +1. **Level 1**: View only +2. **Level 2**: Basic editing, milestone management +3. **Level 3**: Approval capabilities +4. **Level 4**: Full control including deletion +5. **Level 5**: System administration + +Each level inherits permissions from lower levels. diff --git a/client/src/assets/icons/poam-field-definitions.md b/client/src/assets/icons/poam-field-definitions.md new file mode 100644 index 00000000..aa404caa --- /dev/null +++ b/client/src/assets/icons/poam-field-definitions.md @@ -0,0 +1,68 @@ +################################# +POAM Field Definitions +################################# + +Core Field Definitions +===================== + +Description +---------- +"Control Vulnerability Description: Describes the vulnerability identified during assessment. This is pulled directly from the assessment procedure entry or technical assessment method (e.g., STIG test case) where applicable. Otherwise it must be manually entered in the NC status for the vulnerability." + +Source Identifying Control Vulnerability +------------------------------------- +"Source Identifying Control Vulnerability: Identifies the source of the vulnerability (e.g., program review, test and evaluation program findings, IG DoD audit, and GAO audit)." + +Vulnerability ID +-------------- +"Security Checks - NIST -53Rev 4 Assessment Procedure, STIG / SRG Vulnerability ID, or ACAS Plugin ID (Do not leave this field blank)." + +Risk & Impact Fields +=================== + +Raw Severity +---------- +"Raw Severity: The initial or starting severity of the vulnerability prior to implementing mitigations and/or compensating Controls." + +Adjusted Severity +--------------- +"Resulting Residual Risk after Proposed Mitigations: The risk level expected after any proposed mitigations are implemented. Proposed mitigations should be appropriately documented as POA&M milestones" + +Impact Description +---------------- +"Impact Description: Describe the identified impact." + +Predisposing Conditions +--------------------- +"Predisposing Conditions: A condition existing within an organization, a mission or business process, enterprise architecture, information system, or environment of operation, which affects (i.e., increases or decreases) the likelihood that threat events, once initiated, result in adverse impacts." + +Scheduling & Resources +==================== + +Scheduled Completion Date +----------------------- +"Scheduled Completion Date: Target completion date for resolving the vulnerability. This target completion date can stretch beyond the potential 3-year authorization window and must accurately reflect the resolution timetable. Please note that the initial date entered may not be changed. When a vulnerability severity value is resolved, the agency should note the actual completion date." + +Required Resources +---------------- +"Resources Required: Estimated funding or manpower resources required to resolve the security vulnerability (i.e., full-time equivalent)." + +Milestones +--------- +"Milestone with Completion Dates: A milestone identifies specific requirements for correcting an identified vulnerability. The initial milestones and completion dates may not be altered. Any changes to the milestones should be noted in the Milestone Changes within the POAM extension panel." + +Risk Assessment Fields +==================== + +Residual Risk +------------ +"Residual Risk is automatically determined by the Adjusted Severity Value. If the Adjusted Severity Value is not present, the Residual Risk is determined by the Raw Severity." + +Likelihood +--------- +"Likelihood is automatically determined by the Adjusted Severity Value. If the Adjusted Severity Value is not present, the Likelihood is determined by the Raw Severity." + +Mitigations +---------- +"Mitigations: Any currently implemented mitigations and/or compensating Controls that will reduce the risk. A planned mitigation or compensating Control cannot lower risk until implemented." + diff --git a/client/src/assets/icons/poam-user-documentation.md b/client/src/assets/icons/poam-user-documentation.md new file mode 100644 index 00000000..de1f0302 --- /dev/null +++ b/client/src/assets/icons/poam-user-documentation.md @@ -0,0 +1,244 @@ +################################# +POAM User Guide +################################# + +Overview +======== +The Plan of Action & Milestones (POAM) interface allows users to document, track, and manage security vulnerabilities. This guide covers the creation methods, field definitions, and management features available in the system. + +POAM Creation Methods +==================== + +Automated POAM Creation +---------------------- + +STIG Manager Integration +~~~~~~~~~~~~~~~~~~~~~~~ +When creating a POAM from STIG Manager findings: + +1. The system automatically populates: + * Vulnerability Source (set to "STIG") + * STIG Title and Benchmark ID + * Vulnerability ID + * Description from STIG check + * Raw Severity mapped from STIG finding + * Scheduled completion date (calculated based on severity) + +2. Asset Management: + * The Assets tab displays a live feed of affected assets from STIG Manager + * Assets are automatically updated based on the current state in STIG Manager + * Assets cannot be manually added/removed as they are managed by STIG Manager + +Tenable Integration +~~~~~~~~~~~~~~~~~~ +When creating a POAM from Tenable findings: + +1. The system automatically populates: + * Vulnerability Source (set to "ACAS") + * Plugin ID + * Full vulnerability description from Tenable + * Raw Severity (mapped from Tenable severity) + * IAVM information (when available) + * Scheduled completion date (calculated based on severity) + +2. Asset Management: + * The Assets tab shows real-time affected assets from Tenable + * Asset list updates automatically based on current Tenable scan data + * Assets cannot be manually modified as they reflect live Tenable data + +Manual POAM Creation +------------------- +While not recommended, POAMs can be created manually: + +1. All fields must be entered by the user +2. Assets must be selected manually from the collection's asset list +3. Requires more validation and verification + +Field Definitions +================ + +Basic Information +---------------- + +POAM Status +~~~~~~~~~~~ +Available statuses: +* Draft - Initial state +* Submitted - Ready for review +* Pending CAT-I Approval - Awaiting critical review +* Extension Requested - Time extension pending +* Approved - Validated and accepted +* Rejected - Returned for modification +* Closed - Remediation complete +* False-Positive - Invalid finding +* Expired - Past due without extension + +Description +~~~~~~~~~~ +**Purpose**: Documents the vulnerability identified during assessment +* Pulled directly from assessment procedure or technical findings +* For manual entries, must detail the specific security weakness +* Maximum 10000 characters + +A&A Package +~~~~~~~~~~ +The Authorization & Assessment package associated with the POAM + +Source Identification +------------------- + +Vulnerability Source +~~~~~~~~~~~~~~~~~~ +Identifies the source of the vulnerability: +* STIG +* Assured Compliance Assessment Solution (ACAS) Nessus Scanner +* Program review +* Test and evaluation findings +* IG DoD audit +* GAO audit + +Plugin ID / Vulnerability ID +~~~~~~~~~~~~~~~~~~~~~~~~~~ +* For ACAS: Tenable Plugin ID +* For STIG: STIG check ID +* For other sources: Source-specific identifier + +IAVM Information +~~~~~~~~~~~~~~~ +For ACAS findings only: +* IAVM Number format: YYYY-X-NNNN +* IAV Comply By Date required if IAVM number present +* Links to VRAM for detailed IAV information + +Severity and Risk +--------------- + +Raw Severity +~~~~~~~~~~~ +Initial severity before mitigations: +* CAT I - Critical +* CAT I - High +* CAT II - Medium +* CAT III - Low +* CAT III - Informational + +Adjusted Severity +~~~~~~~~~~~~~~~ +Modified severity after mitigations: +* Requires documentation in Mitigations field if different from Raw Severity +* Automatically updates Residual Risk and Likelihood values +* Available only to CAT-I Approvers (Level 3+) + +Impact Assessment +--------------- + +Local Impact +~~~~~~~~~~~ +Assessed impact to the local environment: +* Very Low +* Low +* Moderate +* High +* Very High + +Impact Description +~~~~~~~~~~~~~~~~ +Required if Local Impact is Moderate or higher: +* Detailed description of the specific impact +* Maximum 2000 characters + +Residual Risk & Likelihood +~~~~~~~~~~~~~~~~~~~~~~~~~ +Automatically calculated based on Adjusted Severity (or Raw Severity if no adjustment): +* System maps severity categories to risk levels +* Cannot be manually modified + +Timeline Management +----------------- + +Scheduled Completion Date +~~~~~~~~~~~~~~~~~~~~~~~ +Automatically calculated based on severity: +* CAT I: 30 days +* CAT II: 180 days +* CAT III: 365 days + +Can be modified within constraints: +* Cannot exceed original date without approved extension +* Must be justified through milestones + +Predisposing Conditions +--------------------- +Documents conditions that affect vulnerability likelihood: +* Organizational factors +* Mission/business process impacts +* Architecture considerations +* Environmental factors + +Required Resources +---------------- +Documents estimated resources needed: +* Funding requirements +* Personnel (FTE) needs +* Equipment or software needs +* Maximum 10000 characters + +Milestones +--------- +Required for POAM submission: +* Minimum one milestone +* Minimum 15 characters in milestone comments +* Must include: + - Milestone comments + - Due date + - Status (Pending/Complete) + - Responsible team + +Validation: +* Milestone dates cannot exceed POAM completion date +* Extensions require separate approval process + +Associated Vulnerabilities +------------------------ +For CAT-I Approvers only: +* Link related vulnerability IDs +* Document relationships between findings +* Track grouped remediation efforts + +Labels +------ +Optional categorization: +* Apply existing labels +* Group related POAMs +* Enable filtered searching + +Attachments +---------- +Supporting documentation: +* Evidence files +* Configuration details +* Remediation plans + +Access Control +============= +Features available based on user level: + +Level 1 (Viewer) +* View POAM details +* Download attachments + +Level 2 (Editor) +* Create/edit POAMs +* Manage milestones +* Upload attachments + +Level 3 (Approver) +* Approve/reject POAMs +* Modify adjusted severity +* Review extensions + +Level 4 (CAT-I Approver) +* Manage associated vulnerabilities +* Delete POAMs +* Full system access + diff --git a/client/src/assets/icons/tenable-filters.md b/client/src/assets/icons/tenable-filters.md new file mode 100644 index 00000000..d2273d52 --- /dev/null +++ b/client/src/assets/icons/tenable-filters.md @@ -0,0 +1,16 @@ +# Tenable Predefined Filters + +| Filter Preset | Applied Filters | +|--------------|----------------| +| Vulnerability Published 30+ Days | - Vulnerability Published: 30+ days | +| Exploitable Findings 7+ Days | - Exploit Available: true
- Vulnerability Published: 7+ days | +| Exploitable Findings 30+ Days | - Exploit Available: true
- Vulnerability Published: 30+ days | +| Critical/High 7+ Days | - Severity: Critical (4), High (3)
- Vulnerability Last Observed: 0-30 days
- Vulnerability Published: 7+ days | +| Critical/High 14+ Days | - Severity: Critical (4), High (3)
- Vulnerability Last Observed: 0-30 days
- Vulnerability Published: 14+ days | +| Critical/High 30+ Days | - Severity: Critical (4), High (3)
- Vulnerability Last Observed: 0-30 days
- Vulnerability Published: 30+ days | +| Medium 180+ Days | - Severity: Medium (2)
- Vulnerability Last Observed: 0-30 days
- Vulnerability Published: 180+ days | +| Low 365+ Days | - Severity: Low (1)
- Vulnerability Last Observed: 0-30 days
- Vulnerability Published: 365+ days | +| Cisco Findings 30+ Days | - Plugin Family: 33
- Vulnerability Last Observed: 0-30 days
- Severity: All (1-4) | +| Database Findings 30+ Days | - Plugin Family: 31
- Vulnerability Last Observed: 0-30 days
- Severity: All (1-4) | +| F5 Findings 30+ Days | - Plugin Family: 57
- Vulnerability Last Observed: 0-30 days
- Severity: All (1-4) | +| Linux/Ubuntu Findings 30+ Days | - Plugin Family: 1, 14
- Vulnerability Last Observed: 0-30 days
- Severity: All (1-4) | diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 00000000..4021b338 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,5 @@ +FROM sphinxdoc/sphinx:7.1.2 + +WORKDIR /docs +ADD requirements.txt /docs +RUN pip3 install -r requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..41c270bb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..745362c7 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,58 @@ +.rst-content .line-block { + margin-bottom: 0; +} + +figcaption { + padding-top: 10px; + font-size: 85%; + font-style: italic; +} + +.tight-table td { + white-space:normal !important; +} + +.wy-nav-content { + width: 100%; + max-width: 1200px !important; +} + +.document a:visited { + color: #2980b9; +} + +.document a { + font-weight: bold; +} + + +h4 { + font-size: 100%; +} + +p.rubric { + margin-bottom: 12px; + font-size: 125%; +} + +p.rubric2 { + margin-bottom: 12px; + font-size: 150%; +} + +p.rubric3 { + margin-bottom: 12px; + font-size: 100%; +} + +p.rubric-big { + margin-bottom: 12px; + font-size: 200%; +} + + +.rst-content .toctree-wrapper>p.caption, h1, h2, h3, h4, h5, h6, legend { + margin-top: 0; + font-weight: 700; + font-family: Lato,ff-tisa-web-pro,Georgia,Arial,sans-serif; +} \ No newline at end of file diff --git a/docs/assets/images/component-diagram.svg b/docs/assets/images/component-diagram.svg new file mode 100644 index 00000000..4e7cb03e --- /dev/null +++ b/docs/assets/images/component-diagram.svg @@ -0,0 +1,3 @@ + + +
C-PAT and STIG Manager
STIG Manager Components
Client
Client
API
API
Database
(MySQL)
Database(MySQL)
Authentication Provider
(Keycloak)
Authentication Provider(Keycloak)
Reverse Proxy
Reverse Proxy \ No newline at end of file diff --git a/docs/assets/images/cpat.svg b/docs/assets/images/cpat.svg new file mode 100644 index 00000000..d1bb12a0 --- /dev/null +++ b/docs/assets/images/cpat.svg @@ -0,0 +1,13 @@ + + + + + + \ No newline at end of file diff --git a/docs/assets/images/k8-component-diagram.svg b/docs/assets/images/k8-component-diagram.svg new file mode 100644 index 00000000..bf1c1907 --- /dev/null +++ b/docs/assets/images/k8-component-diagram.svg @@ -0,0 +1,3 @@ + + +
Kubernetes Environment
Kubernetes Environment
K8 Ingress
K8 Ingress
C-PAT and STIG Manager
STIG Manager Components
Client
Client
API
API
Database
(MySQL)
Database(MySQL)
Authentication Provider
(Keycloak)
Authentication Provider(Keycloak)
Users
Users \ No newline at end of file diff --git a/docs/assets/images/vram_columnOptions.png b/docs/assets/images/vram_columnOptions.png new file mode 100644 index 00000000..dcf4c984 Binary files /dev/null and b/docs/assets/images/vram_columnOptions.png differ diff --git a/docs/assets/images/vram_step1.png b/docs/assets/images/vram_step1.png new file mode 100644 index 00000000..cf28376a Binary files /dev/null and b/docs/assets/images/vram_step1.png differ diff --git a/docs/assets/images/vram_step2.png b/docs/assets/images/vram_step2.png new file mode 100644 index 00000000..ca083f92 Binary files /dev/null and b/docs/assets/images/vram_step2.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..b11be8ca --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,41 @@ +import sphinx_rtd_theme + +project = 'C-PAT' +copyright = '2024 U.S. Federal Government (in countries where recognized)' +author = 'Christian Rodriguez' + +release = '1.0.0-beta.1' +version = '1.0.0-beta.1' + +html_css_files = [ + 'css/custom.css', +] + +extensions = [ + 'sphinx_rtd_theme', + 'sphinx.ext.todo', + 'myst_parser', + 'sphinx_tabs.tabs', + 'sphinxcontrib.images' +] +html_logo = 'assets/images/cpat.svg' +images_config = { + 'override_image_directive': True, + 'default_image_width': '50%', + 'default_group': 'default' +} + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +html_theme = "sphinx_rtd_theme" + +html_theme_options = { + 'logo_only': True, + 'prev_next_buttons_location': 'both', + 'sticky_navigation': True +} +html_show_sphinx = False +html_static_path = ['_static'] +html_output_dir = '_build/html' +epub_show_urls = 'footnote' diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..0f0d91ff --- /dev/null +++ b/docs/index.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..478cb517 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +C-PAT Documentation +======================================== +.. warning:: + C-PAT documentation is currently under development. Please check back for updates. + + +What is C-PAT? +------------------------------- +C-PAT is an API and web client currently being developed through Naval Surface Warfare Center Crane Division that aims to automate vulnerability documentation and tracking. C-PAT is, and will continue to be architected with emphasis towards interoperability with other RMF Tools. C-PAT is designed to integrate with `STIG Manager `_ and `Tenable.sc [Assured Compliance Assessment Solution (ACAS) Nessus Scanner] `_ to provide a more comprehensive solution for oversight throughout the RMF process. + + + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + source/install/index + source/admin/index + source/user/index + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..97bd0d7c --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,24 @@ +@echo off +set SPHINX_IMAGE_W_REQUIREMENTS=sphinx-w-requirements + +REM Change to this script directory +cd /d "%~dp0" + +REM Clean up _build directory +if exist _build ( + for /d %%i in (_build\*) do rmdir /s /q "%%i" + del /q _build\* +) + +REM Build Docker image +docker build -t %SPHINX_IMAGE_W_REQUIREMENTS% . + +REM Run Docker container and copy results +docker run --rm -v "%cd%":/source %SPHINX_IMAGE_W_REQUIREMENTS% /bin/bash -c "cp -r /source/* /docs && make html && cp -r /docs/_build/html /source/_build/" + +REM Check if files were copied +if exist _build\html ( + echo Build successful. Output is in _build\html directory. +) else ( + echo Build may have failed or files were not copied correctly. +) \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..0765f2e1 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,30 @@ +alabaster==0.7.12 +Babel==2.9.1 +certifi==2024.7.4 +chardet==4.0.0 +colorama==0.4.5 +commonmark==0.9.1 +docutils==0.18.1 +idna==3.7 +imagesize==1.4.1 +Jinja2==3.1.4 +Markdown==3.3.3 +MarkupSafe==2.1.3 +packaging==23.2 +Pygments==2.15.0 +pyparsing==2.4.7 +pytz==2021.1 +requests==2.32.0 +myst_parser==2.0.0 +snowballstemmer==2.1.0 +sphinx-rtd-theme==2.0.0 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.4 +sphinxcontrib-images==0.9.4 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.9 +sphinx-tabs==3.4.4 +urllib3==1.26.19 + diff --git a/docs/source/admin/admin-portal.rst b/docs/source/admin/admin-portal.rst new file mode 100644 index 00000000..6d768c64 --- /dev/null +++ b/docs/source/admin/admin-portal.rst @@ -0,0 +1,159 @@ +.. _admin-portal: + +Administration Portal +--------------------- + +The Admin Portal is accessible to users with the ``admin`` role assigned by the OIDC provider and subsequently provided to C-PAT via the user's token. Users whose token contains the admin role will automatically be presented with an "Admin Portal" button in the side menu bar. The Admin Portal provides a way to manage users, collections, integrations, and fine-tune options that best align with particular organizational policies and operations. + +User Management +--------------- + +The User Management section allows administrators to view, manage, and modify user accounts within C-PAT. + +.. note:: + By default, when a user first logs into C-PAT, they are assigned a ``PENDING`` account status and will not be able to access the application until an administrator approves their account. This step is implemented to ensure that only authorized users have access to the application and administrators have the ability and oversight to dictate more precise permissions and access. + + To approve a user account, an administrator must navigate to the User Management section, select the user account from the dropdown at the bottom of the User Table, and change the Account Status to ``ACTIVE``. Once approved, the user will be able to access the application and navigate to any collections for which they have been assigned permissions. + +Assuming a correct C-PAT and OIDC configuration, user data *should* be automatically populated from the OIDC provider. If the user data is not automatically populated, the user data can be manually entered by an administrator. Accurate and complete user data is important to the flow of the C-PAT application, particularly when it comes to exporting into the eMASS excel format. User first name, last name, email, phone number, and office/organization are all pre-populated into a C-PAT export when available. + +C-PAT Collection Privileges +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Privilege + - Allows + * - Viewer + - The Viewer role is most commonly attributed to readonly access. Users who have been granted the Viewer role for a collection can view the collection and its associated POAMs, Assets, Labels, etc. Users with the Viewer role however, cannot make any changes or add new items. + * - Submitter + - The Submitter role is the recommended role for users who should not be restricted to readonly access and who do not explicitly need POAM approval access for the collection. Users with Submitter access will have access to add and modify data for POAMs, Assets, Labels, etc. + * - Approver + - The Approver role is the recommended role for users who need to approve POAMs for the collection. Users with the Approver role will have the same access as that of the Submitter role, in addition to access to issue final approval or rejection for CAT II and CAT III POAMs. In the case of CAT I POAMs, an Approver can (and should) review and mark the POAM as approved, but the final approval must be issued by a CAT I Approver. + * - CAT I Approver + - The CAT I Approver role provides the highest level of access to a collection. Users with the CAT I Approver role will have the same access as that of the Approver role, in addition to the ability to issue final approval for CAT I POAMs. CAT I Approvers are the only users who can issue final approval for CAT I POAMs. + +Collection Management +--------------------- + +Collection management provides C-PAT administrators with the ability to manually create new collections, alter existing collections, or export all of the POAMs contained within a collection into the eMASS excel format. + +.. warning:: + Manual creation of collections is not recommended when data ingestion from STIG Manager or Tenable is desired. Collections should be automatically imported via the STIG Manager or Tenable Import section within the Admin Portal to ensure the proper collection association. + +.. note:: + While the Collection Name is the only required field for a collection, it is strongly recommended that all Collection fields are entered to ensure proper data flow within C-PAT. + +Collection Field Mappings +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- **Collection Name**: The name of the collection. For collections that are imported from STIG Manager or Tenable, the collection name should match the collection name from the respective system. The collection name will be displayed in navigation across C-PAT and be contained in the file name of POAM exports. +- **Collection Description**: A brief description of the collection. +- **System Type**: This field will map to Cell ``L2`` in the eMASS format excel export. +- **System Name**: This field will map to Cell ``D5`` in the eMASS format excel export. +- **CC/S/A/FA**: This field will map to Cell ``D4`` in the eMASS format excel export. +- **A&A Package**: C-PAT provides the ability to associate an A&A package with a collection. When a collection has an A&A package set, this field will be automatically populated for any POAM created within the collection. + +Integrations +------------ + +STIG Manager +^^^^^^^^^^^^ + +The STIG Manager component allows administrators to import collections from STIG Manager into C-PAT, or more precisely, create a collection shell that will interface with a particular STIG Manager collection. To import collections: + +1. Navigate to the "STIG Manager" tab in the Admin Portal. +2. You will see a dropdown menu labeled "Select Collection to Import...". +3. Click on the dropdown to view available collections from STIG Manager. +4. Select the collection you wish to import. +5. Click the "IMPORT SELECTED" button to import the chosen collection. +6. To import all remaining collections at once, click the "IMPORT ALL REMAINING" button. + +.. note:: + Once all collections have been imported, the list will be empty, and no items will be displayed. + + After importing a collection, users must still be assigned the appropriate permissions to the newly imported collection before they can view or access it. + +Tenable.sc +^^^^^^^^^^ + +The Tenable Import component enables administrators to import repositories from Tenable.sc as collections in C-PAT. To import repositories: + +1. Go to the "TENABLE IMPORT" tab in the Admin Portal. +2. You will see a dropdown menu labeled "Select Repository to Import...". +3. Click on the dropdown to view available repositories from Tenable.sc. +4. Choose the repository you want to import. +5. Click the "IMPORT SELECTED" button to import the selected repository. +6. To import all remaining repositories at once, click the "IMPORT ALL REMAINING" button. + +.. note:: + Once all repositories have been imported, the list will be empty, and no items will be displayed. + + After importing a repository, users must still be assigned the appropriate permissions to the newly imported collection before they can view or access it. + +The STIG Manager and Tenable Import components streamline the process of creating collections in C-PAT by automatically mapping them to the appropriate external systems, ensuring consistency and reducing manual effort. Currently, there is no way to associate a manually created collection with a STIG Manager collection or Tenable repository. + + + + +VRAM IAV Import +--------------- + +Importing a current VRAM IAV Table into C-PAT is the first step of a two part process as it relates to corelating Navy Comply Dates with Tenable vulnerability findings or plugin IDs. The VRAM IAV Table can be accessed and exported `here `_. + +.. note:: + C-PAT will automatically process the date information is current as of, contained in cell ``A1`` of the VRAM IAV export. All subsequent uploads will compare this date when a new file is uploaded. + +Column Options +^^^^^^^^^^^^^^ +.. note:: + C-PAT is configured to automatically parse the required columns by name, therefore, the default column selections are only a minimum requirement. Additional columns or different column orders in the export are permissible. + At a minimum, the following fields ARE required: ``IAV`` ``Status`` ``Title`` ``IAV CAT`` ``Type`` ``Release Date`` ``Navy Comply Date`` ``Superseded By`` ``Known Exploits`` ``Known DoD Incidents`` ``Nessus Plugins`` + +.. image:: /assets/images/vram_step1.png + :width: 600 + :show_caption: True + :alt: Step 1 - Locate Column Options + :title: Step 1 - Locate Column Options + +.. image:: /assets/images/vram_columnOptions.png + :width: 600 + :show_caption: True + :alt: Step 1.1 - Set Column Options (if necessary) + :title: Step 1.1 - Set Column Options (if necessary) + +Export +^^^^^^ + +Click to export. The exported file can now be imported to C-PAT. + +.. image:: /assets/images/vram_step2.png + :width: 600 + :show_caption: True + :alt: Step 2 - Export + :title: Step 2 - Export + + +Nessus Plugin Mapping +--------------------- + +The 'MAP PLUGINS TO IAV' button will initiate the process of mapping IAV data to Tenable plugin IDs. This is an intensive operation that queries the Tenable analysis endpoint to return plugins with a cross reference[xref] for IAVs from 1990 to present. ``IAVA|20*,IAVB|20*,IAVT|20*,IAVA|199*,IAVB|199*,IAVT|199*`` + +.. note:: + This process will take approximately 60 seconds to complete. Clicking away from the page will terminate the mapping and the process must be started over again. + + + +Set A&A Packages +---------------- + +C-PAT provides the ability for administrators to set A&A package options for their organization. In addition to populating the list of options when setting an A&A package for a particular collection, the A&A packages entered in the Set A&A Packages component will populate a drop down list of options in POAMs for instances when a POAM entry may require deviation from the pre-populated A&A Package. + + + +Set Assigned Teams +------------------ + +Similar to the Set A&A Packages component, the Set Assigned Teams component allows administrators to set a list of teams that can be assigned within POAMs. The teams entered in the Set Assigned Teams component will populate a drop down list of options in POAMs (Step 1 - *Assignees*, Step 8 - *Milestones*, and within the *POAM Extension milestones* section). \ No newline at end of file diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst new file mode 100644 index 00000000..970059bf --- /dev/null +++ b/docs/source/admin/index.rst @@ -0,0 +1,19 @@ + +.. _admin-index: + +Administrative Guide +=============================== + +.. meta:: + :description: C-PAT administrative portal features. + +These pages describe the administrative portal features contained in C-PAT. + + +.. toctree:: + :maxdepth: 2 + :numbered: 4 + :caption: Contents: + + admin-portal + diff --git a/docs/source/install/authentication.rst b/docs/source/install/authentication.rst new file mode 100644 index 00000000..a5c34eed --- /dev/null +++ b/docs/source/install/authentication.rst @@ -0,0 +1,216 @@ +.. _authentication: + + +Authentication and Identity +######################################## + +C-PAT requires an OAuth2 JSON Web Token (JWT) that conforms to the OpenID Connect specification to determine client and user access. The use of the **Authorization Code Flow with Proof Key for Code Exchange** (PKCE)​ flavor of OAuth 2.0​ is highly encouraged for use with the C-PAT web application. To support users that wish to develop their own utilities, we also suggest enabling the Device Authorization Grant Flow. + +C-PAT has been tested to work with Keycloak and Okta as OIDC providers. It is expected to work with other OIDC providers if they can be configured to provide a token that meets the requirements specified below. Please create an Issue with details on our GitHub project if you experience issues with other providers. + +.. note:: + If you are using the RMF Tools demonstration Keycloak container, you may not need to change any settings or variables described in this section. + + +JSON Web Token (JWT) Requirements +---------------------------------- + +The JWT produced by the Identity Provider should provide the claims specified below. Some of them may have different names in your configuration, and can be specified in the C-PAT environment variables if they differ from the default values: + + * Username - ``CPAT_JWT_USERNAME_CLAIM`` - **default:** ``preferred_username`` + * User Full Name - ``CPAT_JWT_FULL_NAME_CLAIM`` - (optional) **default:** ``name`` + * User First Name - ``CPAT_JWT_FIRST_NAME_CLAIM`` - (optional) **default:** ``given_name`` + * User Last Name - ``CPAT_JWT_LAST_NAME_CLAIM`` - (optional) **default:** ``family_name`` + * User Email - ``CPAT_JWT_EMAIL_CLAIM`` - (optional) **default:** ``email`` + * User Privileges - ``CPAT_JWT_PRIVILEGES_CLAIM`` - **default:** ``realm_access.roles`` + * scope - OIDC standard. Use ``CPAT_EXTRA_SCOPES`` to specify additional scopes the client should request. + +.. note:: + C-PAT will use the value specified in the ``CPAT_JWT_USERNAME_CLAIM`` environment variable as the Claim that should hold a users unique username. This value defaults to the Keycloak default, which is ``preferred_username`` + + +.. code-block:: JSON + :caption: The decoded data payload of a sample JWT, with some relevant claims highlighted. + :name: A Decoded JWT + :emphasize-lines: 18,19,20,21,40,42 + + { + "exp": 1695154418, + "iat": 1630360166, + "auth_time": 1630354418, + "jti": "5b17970e-428a-4b54-a0bd-7ed29a436803", + "iss": "http://localhost:8080/auth/realms/RMFTools", + "aud": [ + "realm-management", + "account" + ], + "sub": "eb965d15-aa78-43fc-a2a6-3d86258c1eec", + "typ": "Bearer", + "azp": "c-pat", + "nonce": "2a6a0726-6795-47f5-88a6-00eb8aed9e23", + "session_state": "dca9233f-3d5b-4237-9e6e-be52d90cebdc", + "acr": "0", + "realm_access": { + "roles": [ + "cpat_write", + "admin", + "user" + ] + }, + "resource_access": { + "realm-management": { + "roles": [ + "view-users", + "query-groups", + "query-users" + ] + }, + "account": { + "roles": [ + "manage-account", + "manage-account-links", + "view-profile" + ] + } + }, + "scope": "openid c-pat:read c-pat:write c-pat:op", + "email_verified": false, + "preferred_username": "MisterSeaPat" + } + + +The fields highlighted in the sample token above control the access and information C-PAT requires to allow users to access the application. The token your OIDC provider creates does not need to look exactly like this, but where it differs the relevant claims must be specified using C-PAT Environment Variables. + + +Cross-Origin Resource Sharing (CORS) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your deployment environment has your OIDC Provider and the C-PAT client in different origins (ie. domains), you will need to specify the Client origin in the Web Origins configuration options of your OIDC Provider. This will set the ``Access-Control-Allow-Origin`` header in the OIDC Provider's responses, and permit browsers to make subsequent requests to the OIDC provider. + +Alternatively, you could situate your OIDC Provider and the Client server behind a reverse proxy that is configured to present them both as coming from the same origin, avoiding the problem. + + +.. _oidc-scopes: + +Scopes, and Privileges +--------------------------------- + +The C-PAT API restricts endpoint access using the "scope" claims in the JWT. See the `API specification `_ for details. + +The guide provided below maps scopes to various Realm Roles that are then assigned to Users. +These Roles and Scopes can be provided to users in various ways, using Client Roles, Client Groups, defaults, etc. Please refer to the `Keycloak Documentation `_ for more information. + +The **Roles** specified in the JWT map to Privileges in C-PAT that allow varying levels of access and abilities. See the :ref:`user-roles-privs` section of the Setup Guide for more information. + +The **Scopes** specified in the JWT control access to API endpoints as specified in the OpenAPI spec. See the :ref:`C-PAT Client Scopes and Roles ` table below for a suggestion on how to allocate these scopes using OIDC roles, and more information. + + + +.. note:: + The information provided below is just one way to configure Keycloak to provide a JWT that will work with C-PAT. Please make sure you configure Keycloak in accordance with your organization's Security Policy. + + +.. _keycloak: + +Authentication Example - RedHat Keycloak 19+ +------------------------------------------------------- + +The web client is an OpenID Connect (OIDC) OAuth2 Relying Party and the API is an OAuth2 Resource Server. User authentication is provided by an external Identity Provider (IdP). All API access is controlled by OAUth2 JSON Web Tokens (JWTs) issued by the IdP. User roles are extracted from token claims, endpoint access is controlled by token scope. +Keycloak is readily available, actively maintained by a major OSS vendor, supports Identity Brokering and User Federation, and is used by major DoD projects such as Air Force Iron Bank. +Keycloak supports many External Identity Providers, but has only been tested using its own authentication. +`More information about RedHat Keycloak. `_ + +A sample Keycloak image configured for C-PAT, STIG Manager, and containing Demo users, can be found `on our Github page. `_ + +Keycloak Configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +The configuration offered below is just one way to create a Keycloak Realm that will authenticate Users for C-PAT. The following items in the Keycloak installation must be created and configured appropriately, and their values passed to C-PAT in the appropriate Environment Variable: + +* Keycloak Realm - suggested value: RMFTools +* Client ID - suggested value: c-pat + +Keycloak settings for the "c-pat" realm: + +* Configure->Roles->Realm Roles - Add the following roles: + + * user + * cpat_write + * admin + +.. note:: + These roles can also be set up at the Client level, rather than the Realm level. Make adjustments accordingly. + +* Configure->Roles->Default Roles - Recommended: set "user" and "cpat_write" as default roles. +* Configure->Client Scopes - Create the following scopes, and assign them the specified roles in that scope's "Scope" tab: + +.. _oidc-scopes-table: + + + .. list-table:: C-PAT Client Scopes and Roles: + :widths: 20 70 + :header-rows: 1 + :class: tight-table + + * - Client Scopes + - Roles + * - c-pat:read + - user + * - c-pat:write + - cpat_write + * - c-pat:op + - admin + + +* Configure->Clients->c-pat: + + * Settings: + + * Enable Authorization Code Flow with PKCE (Called "Standard Flow" in Keycloak) + * Valid Redirect URIs - The URI at which your users will access C-PAT. + * Web Origins - Configure according to Organizational requirements. + + * Client Scopes: + + * Add the scopes created above as Assigned Optional Client Scopes. + + +Other suggested Keycloak settings for the c-pat client: + + * Client or SSO Session Idle: 10 minutes + * The "preferred_username" claim in the token should hold the username you intend to be used in C-PAT (this is the default setting). If changed, use `CPAT_JWT_SERVICENAME_CLAIM` to specify. + * Set "OAuth 2.0 Device Authorization Grant Enabled" to "On." + +For other settings, the default Keycloak settings should work. + +Configure C-PAT to use your Authentication provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most commonly, C-PAT will require the below Environment Variable to be specified, unless their default values are appropriate. Check the :ref:`Environment Variables` document for an exhaustive list of Environment Variables and their default values. + +.. list-table:: C-PAT OIDC Environmenment Variables: + :widths: 20 25 55 + :header-rows: 1 + :class: tight-table + + * - Variable + - Default + - Description + * - ``CPAT_OIDC_PROVIDER`` + - ``http://localhost:8080/auth/realms/RMFTools`` + - The base URL of the OIDC provider issuing signed JWTs for the API. The string ``/.well-known/openid-configuration`` will be appended when fetching metadata. + * - ``CPAT_CLIENT_OIDC_PROVIDER`` + - ``CPAT_OIDC_PROVIDER`` + - Client override of the base URL of the OIDC provider issuing signed JWTs for the API. The string ``/.well-known/openid-configuration`` will be appended when fetching metadata. + * - ``CPAT_OAUTH_CLIENTID`` + - ``c-pat`` + - The OIDC clientId for C-PAT. + * - ``CPAT_JWT_PRIVILEGES_CLAIM`` + - ``realm_access.roles`` + - The access token claim whose value is the user’s privileges. + * - ``CPAT_CLIENT_EXTRA_SCOPES`` + - **No default** + - Scopes to request in addition to: ``c-pat:read`` ``c-pat:write`` ``c-pat:op`` ``openid`` + +A sample Keycloak image, recommended only for testing purposes, is available on `Github. `_ Most of the default values for the above Environment variables will work with this image. + diff --git a/docs/source/install/cpat-asd-full.csv b/docs/source/install/cpat-asd-full.csv new file mode 100644 index 00000000..7d4f7d4b --- /dev/null +++ b/docs/source/install/cpat-asd-full.csv @@ -0,0 +1,287 @@ +Vuln,Title,result,Detail +V-222387,The application must provide a capability to limit the number of logon sessions per user.,Informational,"The User Session layer, including concurrent session handling, is implemented by an external OpenID Connect (OIDC) Provider that issues OAuth2 tokens." +V-222388,The application must clear temporary storage and cookies when the session is terminated.,Not a Finding,"The Web Client does not persist storage of any user information, including OAuth2 tokens." +V-222389,The application must automatically terminate the non-privileged user session and log off non-privileged users after a 15 minute idle time period has elapsed.,Informational,"The User Session layer, including idle session handling, is implemented by an external OpenID Connect (OIDC) Provider that issues OAuth2 tokens." +V-222390,The application must automatically terminate the admin user session and log off admin users after a 10 minute idle time period is exceeded.,Informational,"The User Session layer, including idle session handling, is implemented by an external OpenID Connect (OIDC) Provider that issues OAuth2 tokens." +V-222391,Applications requiring user access authentication must provide a logoff capability for user initiated communication session.,Not a Finding,The Web Client requests logoff service from the OIDC Provider after user interaction with a DOM element whose innerText = ?Logout? +V-222392,The application must display an explicit logoff message to users indicating the reliable termination of authenticated communications sessions.,Not a Finding,"The SPA does not display an explicit ?logged out? screen, it immediately redirects to the login screen of the configured OIDC Provider." +V-222393,The application must associate organization-defined types of security attributes having organization-defined security attribute values with information in storage.,Not a Finding,"The API scaffolds each new database instance with the classification specified by the environment variable STIGMAN_CLASSIFICATION. This value is stored in the ?configuration? table and represents the default classification for all data that is stored by the database instance, served by the API, and received by the Web Client." +V-222394,The application must associate organization-defined types of security attributes having organization-defined security attribute values with information in process.,Not a Finding,Individual objects do not contain data markings. An API endpoint returns the data marking for all data served by the API. The Web Client displays a banner that represents the data marking for all data received by the Client. Processing the data does not alter this banner in any circumstances. +V-222395,The application must associate organization-defined types of security attributes having organization-defined security attribute values with information in transmission.,Not a Finding,Individual objects do not contain data markings. An API endpoint returns the data marking for all data served by the API. The Web Client displays a banner that represents the data marking for all data received by the Client. Data transmission does not alter this banner in any circumstances. +V-222396,The application must implement DoD-approved encryption to protect the confidentiality of remote access sessions.,Informational,The documentation recommends deployments locate the application behind a TLS reverse proxy. +V-222397,The application must implement cryptographic mechanisms to protect the integrity of remote access sessions.,Informational,The documentation recommends deployments locate the application behind a TLS reverse proxy. +V-222398,Applications with SOAP messages requiring integrity must include the following message elements:-Message ID-Service Request-Timestamp-SAML Assertion (optionally included in messages) and all elements of the message must be digitally signed.,Not Applicable,The SPA does not utilize SOAP messages. +V-222399,Messages protected with WS_Security must use time stamps with creation and expiration times.,Not Applicable,The SPA does not utilize WS-Security tokens. +V-222400,Validity periods must be verified on all application messages using WS-Security or SAML assertions.,Not Applicable,The SPA does not utilize WSS or SAML assertions. +V-222401,The application must ensure each unique asserting party provides unique assertion ID references for each SAML assertion.,Not Applicable,The SPA does not utilize SAML assertions. +V-222402,"The application must ensure encrypted assertions, or equivalent confidentiality protections are used when assertion data is passed through an intermediary, and confidentiality of the assertion data is required when passing through the intermediary.",Not Applicable,The SPA does not utilize WS-Security tokens +V-222403,The application must use the NotOnOrAfter condition when using the SubjectConfirmation element in a SAML assertion.,Not Applicable,The SPA does not utilize SAML assertions. +V-222404,The application must use both the NotBefore and NotOnOrAfter elements or OneTimeUse element when using the Conditions element in a SAML assertion.,Not Applicable,The SPA does not utilize SAML assertions. +V-222405,"The application must ensure if a OneTimeUse element is used in an assertion, there is only one of the same used in the Conditions element portion of an assertion.",Not Applicable,The SPA does not utilize SAML assertions. +V-222406,The application must ensure messages are encrypted when the SessionIndex is tied to privacy data.,Not Applicable,The SPA does not utilize SAML assertions. +V-222407,The application must provide automated mechanisms for supporting account management functions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222408,Shared/group account credentials must be terminated when members leave the group.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222409,The application must automatically remove or disable temporary user accounts 72 hours after account creation.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222410,"The application must have a process, feature or function that prevents removal or disabling of emergency accounts.",Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222411,The application must automatically disable accounts after a 35 day period of account inactivity.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222412,"Unnecessary application accounts must be disabled, or deleted.",Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222413,The application must automatically audit account creation.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222414,The application must automatically audit account modification.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222415,The application must automatically audit account disabling actions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222416,The application must automatically audit account removal actions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222417,The application must notify System Administrators and Information System Security Officers when accounts are created.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222418,The application must notify System Administrators and Information System Security Officers when accounts are modified.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222419,The application must notify System Administrators and Information System Security Officers of account disabling actions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222420,The application must notify System Administrators and Information System Security Officers of account removal actions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222421,The application must automatically audit account enabling actions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222422,The application must notify System Administrators and Information System Security Officers of account enabling actions.,Informational,Account Management services are provided by an external (OIDC) OpenID Connect Provider. +V-222423,Application data protection requirements must be identified and documented.,Not a Finding,"The project provides documentation describing its data structures and protection methods, including RBAC and other access controls. These concepts are also expressed and enforced by its use of an appropriate OAS definition. All app data is persisted in a deployment-provided database that must be configured in accordance with organization requirements." +V-222424,The application must utilize organization-defined data mining detection techniques for organization-defined data storage objects to adequately detect data mining attempts.,Informational,"Data mining detection and prevention are to be implemented at the Log Analysis layer, Ingress controller, or elsewhere. No data mining protection requirements apply to application itself." +V-222425,The application must enforce approved authorizations for logical access to information and system resources in accordance with applicable access control policies.,Not a Finding,The API ensures proper access to application resources in accordance with Role-Based Access Control (RBAC) and Discretionary Access Control (DAC) mechanisms at the application and Collection levels. No direct database access is provided by the application. See documentation. +V-222426,The application must enforce organization-defined discretionary access control policies over defined subjects and objects.,Not a Finding,The API ensures proper access to application resources in accordance with Role-Based Access Control (RBAC) and Discretionary Access Control (DAC) mechanisms at the application and Collection levels. No direct database access is provided by the application. See documentation. +V-222427,The application must enforce approved authorizations for controlling the flow of information within the system based on organization-defined information flow control policies.,Informational,"The application does not provide data flow control capabilities, the requirement is not applicable." +V-222428,The application must enforce approved authorizations for controlling the flow of information between interconnected systems based on organization-defined information flow control policies.,Informational,"The application does not provide data flow control capabilities, the requirement is not applicable." +V-222429,"The application must prevent non-privileged users from executing privileged functions to include disabling, circumventing, or altering implemented security safeguards/countermeasures.",Not a Finding,"The Project publishes container images configured to execute the API as the unprivileged user, ?node? whose userId is not 0." +V-222430,The application must execute without excessive account permissions.,Not a Finding,"The project supplied container images are configured to run by the limited, unprivileged user, ?node?." +V-222431,The application must audit the execution of privileged functions.,Not a Finding,"The API emits audit records for privileged functions that document the specific endpoint invoked, the date and time, and all path and query parameters." +V-222432,The application must enforce the limit of three consecutive invalid logon attempts by a user during a 15 minute time period.,Informational,User Account services are provided by a external OIDC Provider. +V-222433,The application administrator must follow an approved process to unlock locked user accounts.,Informational,User Account services are provided by a external OIDC Provider. +V-222434,The application must display the Standard Mandatory DoD Notice and Consent Banner before granting access to the application.,Informational,"The Standard Mandatory DoD Notice and Consent Banner can be displayed by the external OIDC Provider, additionally the application is configured to display a standard Consent Banner after authentication through the OIDC Provider." +V-222435,The application must retain the Standard Mandatory DoD Notice and Consent Banner on the screen until users acknowledge the usage conditions and take explicit actions to log on for further access.,Informational,"Standard Mandatory DoD Notice and Consent Banner services are provided by a external OIDC Provider, and the organic C-PAT Consent Banner persists until the user acknowledges through an ""OK"" button." +V-222436,The publicly accessible application must display the Standard Mandatory DoD Notice and Consent Banner before granting access to the application.,Informational,Standard Mandatory DoD Notice and Consent Banner services are provided by a external OIDC Provider. +V-222437,The application must display the time and date of the users last successful logon.,Informational,User Session services are provided by a external OIDC Provider. +V-222438,The application must protect against an individual (or process acting on behalf of an individual) falsely denying having performed organization-defined actions to be covered by non-repudiation.,Informational,C-PAT does not have any non-repudiation requirements as part of its design. +V-222439,"For applications providing audit record aggregation, the application must compile audit records from organization-defined information system components into a system-wide audit trail that is time-correlated with an organization-defined level of tolerance for the relationship between time stamps of individual records in the audit trail.",Informational,C-PAT does not offer log aggregation services. This is expected to be implemented by specific deployments at the Log Analysis level. +V-222441,The application must provide audit record generation capability for the creation of session IDs.,Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222442,The application must provide audit record generation capability for the destruction of session IDs.,Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222443,The application must provide audit record generation capability for the renewal of session IDs.,Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222444,The application must not write sensitive data into the application logs.,Not a Finding,"The API does not emit audit records with sensitive data, including session Ids (not used), encryption keys, or passwords (not used)." +V-222445,The application must provide audit record generation capability for session timeouts.,Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222446,The application must record a time stamp indicating when the event occurred.,Not a Finding,The API emits audit records that are time stamped. +V-222447,"The application must provide audit record generation capability for HTTP headers including User-Agent, Referer, GET, and POST.",Not a Finding,An environment variable is provided for allowing different log levels and configuration to affect headers included in audit record. +V-222448,The application must provide audit record generation capability for connecting system IP addresses.,Not a Finding,"When logging endpoint requests, the API emits audit records that include the original source IP address." +V-222449,The application must record the username or user ID of the user associated with the event.,Not a Finding,"When logging endpoint requests, the API emits audit records that include the OAuth2 token claim configured as representing the requesting entity?s username." +V-222450,The application must generate audit records when successful/unsuccessful attempts to grant privileges occur.,Not a Finding,An environment variable is provided for allowing different log levels and configuration to affect content included in audit record. +V-222451,The application must generate audit records when successful/unsuccessful attempts to access security objects occur.,Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to access security objects (i.e., Collections, Assets, POAMs)." +V-222452,The application must generate audit records when successful/unsuccessful attempts to access security levels occur.,Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to access security levels." +V-222453,"The application must generate audit records when successful/unsuccessful attempts to access categories of information (e.g., classification levels) occur.",Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to access all categories of information." +V-222454,The application must generate audit records when successful/unsuccessful attempts to modify privileges occur.,Not a Finding,An environment variable is provided for allowing different log levels and configuration to affect content included in audit record. +V-222455,The application must generate audit records when successful/unsuccessful attempts to modify security objects occur.,Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to modify security objects." +V-222456,The application must generate audit records when successful/unsuccessful attempts to modify security levels occur.,Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to modify security levels." +V-222457,"The application must generate audit records when successful/unsuccessful attempts to modify categories of information (e.g., classification levels) occur.",Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to modify categories of information." +V-222458,The application must generate audit records when successful/unsuccessful attempts to delete privileges occur.,Not a Finding,An environment variable is provided for allowing different log levels and configuration to affect content included in audit record. +V-222459,The application must generate audit records when successful/unsuccessful attempts to delete security levels occur.,Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to delete security levels." +V-222460,The application must generate audit records when successful/unsuccessful attempts to delete application database security objects occur.,Not a Finding,"The API does not implement functionality that manipulates database security objects, including deletions." +V-222461,"The application must generate audit records when successful/unsuccessful attempts to delete categories of information (e.g., classification levels) occur.",Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to delete categories of information." +V-222462,The application must generate audit records when successful/unsuccessful logon attempts occur.,Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222463,The application must generate audit records for privileged activities or other system-level access.,Informational,"By design, privileged access does not include the ability to modify the application or its configuration. It only provide users with the functionality or the ability to manage their own user specific preferences or otherwise tailor the application to suit individual user needs based upon choices or selections built into the application." +V-222464,The application must generate audit records showing starting and ending time for user access to the system.,Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222465,The application must generate audit records when successful/unsuccessful accesses to objects occur.,Not a Finding,"When logging endpoint requests, the API emits audit records for successful and unsuccessful attempts to access to application objects." +V-222466,The application must generate audit records for all direct access to the information system.,Informational,The application does not provide direct access to the underlying information system. +V-222467,"The application must generate audit records for all account creations, modifications, disabling, and termination events.",Informational,"The web app delegates these duties to an OIDC Provider. The OpenID Connect (OIDC) Provider creates, manages and logs user session data." +V-222468,The application must initiate session auditing upon startup.,Not a Finding,"The API emits audit records immediately upon the start of its bootstrapping process. Your local definition of ?application startup? may include other components (i.e, OIDC Provider, database, reverse proxies, log servers, etc.) whose compliance with this check must be individually evaluated." +V-222469,The application must log application shutdown events.,Not a Finding,"The API emits audit records after receiving the SIGINT or SIGTERM signal that initiates a shutdown. Your local definition of ?application shutdown? may include other components (i.e, OIDC Provider, database, reverse proxies, log servers, etc.) whose compliance with this check must be individually evaluated." +V-222470,The application must log destination IP addresses.,Not a Finding,The API emits audit records containing the destination IP when retrieving token signing keys from the OIDC Provide. +V-222471,The application must log user actions involving access to data.,Not a Finding,"When logging endpoint requests, the API emits audit records for user actions involving access to data." +V-222472,The application must log user actions involving changes to data.,Not a Finding,"When logging endpoint requests, the API emits audit records for user actions involving changes to data." +V-222473,The application must produce audit records containing information to establish when (date and time) the events occurred.,Not a Finding,The API emits audit records that are time stamped. +V-222474,"The application must produce audit records containing enough information to establish which component, feature or function of the application triggered the audit event.",Not a Finding,The API emits audit records that include a component property. +V-222475,When using centralized logging; the application must include a unique identifier in order to distinguish itself from other application logs.,Not a Finding,The API emits audit records that include an instance property. +V-222476,The application must produce audit records that contain information to establish the outcome of the events.,Not a Finding,"When logging endpoint requests, the API emits audit records that contain the response status code." +V-222477,The application must generate audit records containing information that establishes the identity of any individual or process associated with the event.,Not a Finding,"When logging endpoint requests, the API emits audit records that include the OAuth2 token claim configured as representing the requesting entity?s username." +V-222478,The application must generate audit records containing the full-text recording of privileged commands or the individual identities of group account users.,Not a Finding,"When logging endpoint requests, if the request includes parameter ?elevate? == true, the API emits audit records that include the JSON POST content and the JSON reply" +V-222479,The application must implement transaction recovery logs when transaction based.,Informational,Implemented by the Data Storage layer +V-222480,The application must provide centralized management and configuration of the content to be captured in audit records generated by all application components.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222481,The application must off-load audit records onto a different system or media than the system being audited.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222482,The application must be configured to write application logs to a centralized log repository.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222483,The application must provide an immediate warning to the SA and ISSO (at a minimum) when allocated audit record storage volume reaches 75% of repository maximum audit record storage capacity.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222484,Applications categorized as having a moderate or high impact must provide an immediate real-time alert to the SA and ISSO (at a minimum) for all audit failure events.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222485,The application must alert the ISSO and SA (at a minimum) in the event of an audit processing failure.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222486,The application must shut down by default upon audit failure (unless availability is an overriding concern).,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution. Application must be stopped by the Container Platform layer (e.g., k8s)." +V-222487,The application must provide the capability to centrally review and analyze audit records from multiple components within the system.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222488,The application must provide the capability to filter audit records for events of interest based upon organization-defined criteria.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222489,The application must provide an audit reduction capability that supports on-demand reporting requirements.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222490,The application must provide an audit reduction capability that supports on-demand audit review and analysis.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222491,The application must provide an audit reduction capability that supports after-the-fact investigations of security incidents.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222492,The application must provide a report generation capability that supports on-demand audit review and analysis.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222493,The application must provide a report generation capability that supports on-demand reporting requirements.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222494,The application must provide a report generation capability that supports after-the-fact investigations of security incidents.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222495,The application must provide an audit reduction capability that does not alter original content or time ordering of audit records.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222496,The application must provide a report generation capability that does not alter original content or time ordering of audit records.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222497,The applications must use internal system clocks to generate time stamps for audit records.,Not a Finding,The API emits audit records with a time stamp generated from the system clock. +V-222498,The application must record time stamps for audit records that can be mapped to Coordinated Universal Time (UTC) or Greenwich Mean Time (GMT).,Not a Finding,"The API emits audit records with the time stamp represented as an ISO-8601 string, including time zone." +V-222499,The application must record time stamps for audit records that meet a granularity of one second for a minimum degree of precision.,Not a Finding,The API emits audit records with millisecond time stamp precision. +V-222500,The application must protect audit information from any type of unauthorized read access.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222501,The application must protect audit information from unauthorized modification.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222502,The application must protect audit information from unauthorized deletion.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222503,The application must protect audit tools from unauthorized access.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222504,The application must protect audit tools from unauthorized modification.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222505,The application must protect audit tools from unauthorized deletion.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222506,The application must back up audit records at least every seven days onto a different system or system component than the system or component being audited.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222507,The application must use cryptographic mechanisms to protect the integrity of audit information.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222508,Application audit tools must be cryptographically hashed.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution. The project does not provide a separate tool in the form of a file which provides an ability to view and manipulate application log data, query data, or generate reports" +V-222509,The integrity of the audit tools must be validated by checking the files for changes in the cryptographic hash value.,Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution. The project does not provide a separate tool in the form of a file which provides an ability to view and manipulate application log data, query data or generate reports." +V-222510,The application must prohibit user installation of software without explicit privileged status.,Informational,"The project does not provide the ability to install software components, modules, plugins, or extensions," +V-222511,The application must enforce access restrictions associated with changes to application configuration.,Informational,"The application cannot configure itself, and does not offer any configuration mechanisms that are affected by users or config files." +V-222512,The application must audit who makes configuration changes to the application.,Informational,"The application cannot configure itself, and does not offer any configuration mechanisms that are affected by users or config files. The project should be deployed with a Application Services layer (Container Platform such as k8s) that audits configuration changes to the application." +V-222513,"The application must have the capability to prevent the installation of patches, service packs, or application components without verification the software component has been digitally signed using a certificate that is recognized and approved by the organization.",Informational,The application is offered as containerized API/Web Client builds that are signed using Docker Content Trust. +V-222514,The applications must limit privileges to change the software resident within software libraries.,Not a Finding,The API is designed to be stateless and runnable in a read-only container. +V-222515,An application vulnerability assessment must be conducted.,Informational,"Deployments must be scanned according to individual or organizational policies. Developers scan the codebase regularly in a test environment, but this is only one component of a functioning production deployment." +V-222516,"The application must prevent program execution in accordance with organization-defined policies regarding software program usage and restrictions, and/or rules authorizing the terms and conditions of software program usage.",Informational,"Organization-defined policies regarding software program usage and restrictions, and/or rules authorizing the terms and conditions of software program usage are determined locally and not by the project." +V-222517,"The application must employ a deny-all, permit-by-exception (whitelist) policy to allow the execution of authorized software programs.",Not Applicable,"The application is not a configuration management or similar type of application designed to manage system processes and configurations, this requirement is not applicable." +V-222518,The application must be configured to disable non-essential capabilities.,Not a Finding,The application runs only essential services needed for operation. Container images are based on either the Alpine Linux distribution or the Iron Bank Universal Base Image (UBI). +V-222519,"The application must be configured to use only functions, ports, and protocols permitted to it in the PPSM CAL.",Informational,PPS features are implemented by the Container Platform service. +V-222520,The application must require users to reauthenticate when organization-defined circumstances or situations require reauthentication.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. Reauthentication policies are locally defined and implemented. +V-222521,The application must require devices to reauthenticate when organization-defined circumstances or situations requiring reauthentication.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. Reauthentication policies are locally defined and implemented. +V-222522,The application must uniquely identify and authenticate organizational users (or processes acting on behalf of organizational users).,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222523,The application must use multifactor (Alt. Token) authentication for network access to privileged accounts.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222524,The application must accept Personal Identity Verification (PIV) credentials.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222525,The application must electronically verify Personal Identity Verification (PIV) credentials.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. Reauthentication policies are locally defined and implemented. +V-222526,"The application must use multifactor (e.g., CAC, Alt. Token) authentication for network access to non-privileged accounts.",Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222527,The application must use multifactor (Alt. Token) authentication for local access to privileged accounts.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222528,"The application must use multifactor (e.g., CAC, Alt. Token) authentication for local access to non-privileged accounts.",Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222529,The application must ensure users are authenticated with an individual authenticator prior to using a group authenticator.,Not Applicable,The project does not use group or shared accounts. +V-222530,The application must implement replay-resistant authentication mechanisms for network access to privileged accounts.,Informational,Replay-resistant authentication mechanisms are implemented by the OIDC Provider. +V-222531,The application must implement replay-resistant authentication mechanisms for network access to non-privileged accounts.,Informational,Replay-resistant authentication mechanisms are implemented by the OIDC Provider. +V-222532,The application must utilize mutual authentication when endpoint device non-repudiation protections are required by DoD policy or by the data owner.,Informational,Mutual authentication mechanisms are implemented by the OIDC Provider. +V-222533,The application must authenticate all network connected endpoint devices before establishing any connection.,Not a Finding,All API endpoint access requires a valid OAuth2 token issued by the application OIDC Provider. +V-222534,Service-Oriented Applications handling non-releasable data must authenticate endpoint devices via mutual SSL/TLS.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. Devices should perform mutual authentication with the OIDC Provider via the ?client credentials? flow with Signed JWT or equivalent PKI technologies. +V-222535,The application must disable device identifiers after 35 days of inactivity unless a cryptographic certificate is used for authentication.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. Devices should perform mutual authentication with the OIDC Provider via the ?client credentials? flow with Signed JWT or equivalent PKI technologies. +V-222536,The application must enforce a minimum 15-character password length.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222537,The application must enforce password complexity by requiring that at least one upper-case character be used.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222538,The application must enforce password complexity by requiring that at least one lower-case character be used.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222539,The application must enforce password complexity by requiring that at least one numeric character be used.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222540,The application must enforce password complexity by requiring that at least one special character be used.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222541,The application must require the change of at least 8 of the total number of characters when passwords are changed.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222542,The application must only store cryptographic representations of passwords.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222543,The application must transmit only cryptographically-protected passwords.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222544,The application must enforce 24 hours/1 day as the minimum password lifetime.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222545,The application must enforce a 60-day maximum password lifetime restriction.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222546,The application must prohibit password reuse for a minimum of five generations.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222547,The application must allow the use of a temporary password for system logons with an immediate change to a permanent password.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222548,The application password must not be changeable by users other than the administrator or the user with which the password is associated.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222549,The application must terminate existing user sessions upon account deletion.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. Low-latency session termination should be configured on the OIDC Provider. +V-222550,"The application, when utilizing PKI-based authentication, must validate certificates by constructing a certification path (which includes status information) to an accepted trust anchor.",Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222551,"The application, when using PKI-based authentication, must enforce authorized access to the corresponding private key.",Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222552,The application must map the authenticated identity to the individual user or group account for PKI-based authentication.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222553,"The application, for PKI-based authentication, must implement a local cache of revocation data to support path discovery and validation in case of the inability to access revocation information via the network.",Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222554,The application must not display passwords/PINs as clear text.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222555,"The application must use mechanisms meeting the requirements of applicable federal laws, Executive Orders, directives, policies, regulations, standards, and guidance for authentication to a cryptographic module.",Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222556,The application must uniquely identify and authenticate non-organizational users (or processes acting on behalf of non-organizational users).,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222557,The application must accept Personal Identity Verification (PIV) credentials from other federal agencies.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222558,The application must electronically verify Personal Identity Verification (PIV) credentials from other federal agencies.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222559,The application must accept FICAM-approved third-party credentials.,Informational,Authentication services are provided by an external (OIDC) OpenID Connect Provider. +V-222560,The application must conform to FICAM-issued profiles.,Not a Finding,"The project conforms to OpenID Connect, a FICAM issued profile." +V-222561,Applications used for non-local maintenance sessions must audit non-local maintenance and diagnostic sessions for organization-defined auditable events.,Not Applicable,The project does not provide non-local maintenance and diagnostic capability. +V-222562,Applications used for non-local maintenance sessions must implement cryptographic mechanisms to protect the integrity of non-local maintenance and diagnostic communications.,Not Applicable,The project does not provide non-local maintenance and diagnostic capability. +V-222563,Applications used for non-local maintenance sessions must implement cryptographic mechanisms to protect the confidentiality of non-local maintenance and diagnostic communications.,Not Applicable,The project does not provide non-local maintenance and diagnostic capability. +V-222564,Applications used for non-local maintenance sessions must verify remote disconnection at the termination of non-local maintenance and diagnostic sessions.,Not Applicable,The project does not provide non-local maintenance and diagnostic capability. +V-222565,The application must employ strong authenticators in the establishment of non-local maintenance and diagnostic sessions.,Not Applicable,The project does not provide non-local maintenance and diagnostic capability. +V-222566,The application must terminate all sessions and network connections when non-local maintenance is completed.,Not Applicable,The project does not provide non-local maintenance and diagnostic capability. +V-222567,The application must not be vulnerable to race conditions.,Not a Finding,Code review by SonarCloud tests reveal no race conditions. +V-222568,The application must terminate all network connections associated with a communications session at the end of the session.,Not a Finding,The application relies on the underlying OS to control the network connection aspect of the application. +V-222569,"The application must implement NSA-approved cryptography to protect classified information in accordance with applicable federal laws, Executive Orders, directives, policies, regulations, and standards.",Informational,"The project expects other layers to provide appropriate data protection via compliant cryptography. It supports interactions with the Data Storage layer via TLS. The project containers are read-only, stateless builds." +V-222570,The application must utilize FIPS-validated cryptographic modules when signing application components.,Not a Finding,"Container images are signed via Docker Content Trust, which uses SHA256 digests." +V-222571,The application must utilize FIPS-validated cryptographic modules when generating cryptographic hashes.,Not a Finding,"Container images are signed via Docker Content Trust, which uses SHA256 digests." +V-222572,The application must utilize FIPS-validated cryptographic modules when protecting unclassified information that requires cryptographic protection.,Informational,"Conformant data protection techniques should be implemented by the Data Storage service, and/or by Ingress configuration of the Container Platform." +V-222573,Applications making SAML assertions must use FIPS-approved random numbers in the generation of SessionIndex in the SAML element AuthnStatement.,Not Applicable,The project does not use SAML assertions. +V-222574,The application user interface must be either physically or logically separated from data storage and management interfaces.,Not a Finding,"Web application is logically separated from data storage layer. Authorization for privileged access determined by the OIDC Provider, also logically separated. Web application offers no application configuration functionality in the application itself." +V-222575,The application must set the HTTPOnly flag on session cookies.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222576,The application must set the secure flag on session cookies.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222577,The application must not expose session IDs.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222578,The application must destroy the session ID value and/or cookie on logoff or browser close.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222579,Applications must use system-generated session identifiers that protect against session fixation.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222580,Applications must validate session identifiers.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222581,Applications must not use URL embedded session IDs.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222582,The application must not re-use or recycle session IDs.,Informational,The web application does not set session cookies. OIDC Provider must be configured appropriately. +V-222583,"The application must use the Federal Information Processing Standard (FIPS) 140-2-validated cryptographic modules and random number generator if the application implements encryption, key exchange, digital signature, and hash functionality.",Informational,The web application expects OAuth2 tokens to be signed by the OIDC Provider using FIP-140-2 validated algorithms . +V-222584,The application must only allow the use of DoD-approved certificate authorities for verification of the establishment of protected sessions.,Informational,The project expects DoD-approved CAs to be referenced by the OIDC Provider. +V-222585,"The application must fail to a secure state if system initialization fails, shutdown fails, or aborts fail.",Informational,"The project expects fail-safe procedures to be implemented by the Container Platform (i.e, k8s). The web application is provided as a stateless container that caches no data and will not respond with data to requests when components are inoperable or inaccessible. The web client defaults to an empty page and restricts menu-item visibility in the event it does not possess a valid permission validation response, i.e. initialization fails, shutdown fails, or aborts fail." +V-222586,"In the event of a system failure, applications must preserve any information necessary to determine cause of failure and any information necessary to return to operations with least disruption to mission processes.",Informational,"The project expects fail-safe procedures to be implemented by the Container Platform (i.e, k8s). The web application is provided as a stateless container that caches no data and will not respond with data to requests when components are inoperable or inaccessible." +V-222587,The application must protect the confidentiality and integrity of stored information when required by DoD policy or the information owner.,Informational,The project expects conformant data storage procedures to be implemented by the Data Storage layer. +V-222588,The application must implement approved cryptographic mechanisms to prevent unauthorized modification of organization-defined information at rest on organization-defined information system components.,Informational,The project expects conformant data storage procedures to be implemented by the Data Storage layer. +V-222589,The application must use appropriate cryptography in order to protect stored DoD information when required by the information owner or DoD policy.,Informational,The project expects conformant data storage procedures to be implemented by the Data Storage layer. +V-222590,The application must isolate security functions from non-security functions.,Not a Finding,The project RBAC is described in the documentation. +V-222591,The application must maintain a separate execution domain for each executing process.,Not a Finding,"The project should be deployed as an immutable, stateless container that runs in a single, isolated execution domain." +V-222592,Applications must prevent unauthorized and unintended information transfer via shared system resources.,Not a Finding,"The project should be deployed as an immutable, stateless container that is isolated from other host processes (i.e, k8s)" +V-222593,"XML-based applications must mitigate DoS attacks by using XML filters, parser options, or gateways.",Not a Finding,"The project does not parse XML. File parsing is limited to .XLS, .XLSX, .XLSM with appropriate validations in place to ensure file-type. Subsequent handling is performed by ""ExcelJS"" or ""XLSX"" which both undergo routine scans and testing to ensure protections against related attacks." +V-222594,The application must restrict the ability to launch Denial of Service (DoS) attacks against itself or other information systems.,Informational,The project expects to be deployed in a Container Platform that resists DoS attacks. +V-222595,The web service design must include redundancy mechanisms when used with high-availability systems.,Informational,The project expects to be deployed in a Container Platform that provides high-availability services. +V-222596,The application must protect the confidentiality and integrity of transmitted information.,Informational,The project expects to be deployed in a Container Platform that protects the confidentiality and integrity of transmitted information. +V-222597,"The application must implement cryptographic mechanisms to prevent unauthorized disclosure of information and/or detect changes to information during transmission unless otherwise protected by alternative physical safeguards, such as, at a minimum, a Protected Distribution System (PDS).",Informational,The project expects to be deployed in a Container Platform that protects the confidentiality and integrity of transmitted information. +V-222598,The application must maintain the confidentiality and integrity of information during preparation for transmission.,Informational,The project expects to be deployed in a Container Platform that protects the confidentiality and integrity of transmitted information. +V-222599,The application must maintain the confidentiality and integrity of information during reception.,Informational,The project expects to be deployed in a Container Platform that protects the confidentiality and integrity of transmitted information. +V-222600,The application must not disclose unnecessary information to users.,Not a Finding,"Resources are disclosed in accordance with Role-Based Access Control (RBAC) and Discretionary Access Control (DAC) mechanisms at the application and Collection levels, error messages and other revealed information are sanitized to ensure no release of sensitive or unnecessary information." +V-222601,The application must not store sensitive information in hidden fields.,Not a Finding,"No sensitive authentication or session data is stored in hidden fields. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222602,The application must protect from Cross-Site Scripting (XSS) vulnerabilities.,Not a Finding,"SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222603,The application must protect from Cross-Site Request Forgery (CSRF) vulnerabilities.,Not a Finding,"SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222604,The application must protect from command injection.,Not a Finding,"SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222605,The application must protect from canonical representation vulnerabilities.,Not a Finding,"SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222606,The application must validate all input.,Not a Finding,"API input is validated against the OAS definition. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222607,The application must not be vulnerable to SQL Injection.,Not a Finding,"All SQL queries that process user input are parameterized. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222608,The application must not be vulnerable to XML-oriented attacks.,Not a Finding,"SonarCloud scans are run regularly to identify XML vulnerabilities. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222609,The application must not be subject to input handling vulnerabilities.,Not a Finding,"All user input is validated on both the client and the server. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222610,The application must generate error messages that provide information necessary for corrective actions without revealing information that could be exploited by adversaries.,Not a Finding,"Resources are disclosed in accordance with Role-Based Access Control (RBAC) and Discretionary Access Control (DAC) mechanisms at the application and Collection levels, error messages and other revealed information are sanitized to ensure no release of sensitive or unnecessary information." +V-222611,"The application must reveal error messages only to the ISSO, ISSM, or SA.",Not a Finding,Error messages addressed by Issue #483 +V-222612,The application must not be vulnerable to overflow attacks.,Not a Finding,"SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222613,The application must remove organization-defined software components after updated versions have been installed.,Not a Finding,"Dependabot services provided by GitHub to identify vulnerable software components. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222614,Security-relevant software updates and patches must be kept up to date.,Not a Finding,"Dependabot services provided by GitHub to identify vulnerable software components. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Advisories page on GitHub for any known vulnerabilities." +V-222615,The application performing organization-defined security functions must verify correct operation of security functions.,Not Applicable,The application is not designed or intended to perform security function testing. +V-222616,The application must perform verification of the correct operation of security functions: upon system startup and/or restart; upon command by a user with privileged access; and/or every 30 days.,Not Applicable,The application is not designed or intended to perform security function testing. +V-222617,The application must notify the ISSO and ISSM of failed security verification tests.,Not Applicable,The application is not designed or intended to perform security function testing. +V-222618,Unsigned Category 1A mobile code must not be used in the application in accordance with DoD policy.,Not Applicable,No Category 1A present in the application. The SPA mobile code executes within the client browser. +V-222619,"The ISSO must ensure an account management process is implemented, verifying only authorized users can gain access to the application, and individual accounts designated as inactive, suspended, or terminated are promptly removed.",Informational,Account management services are provided by the external OpenID Connect (OIDC) Provider. +V-222620,Application web servers must be on a separate network segment from the application and database servers if it is a tiered application operating in the DoD DMZ.,Informational,Determined by deployment configuration. +V-222621,"The ISSO must ensure application audit trails are retained for at least 1 year for applications without SAMI data, and 5 years for applications including SAMI data.",Informational,"Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222622,The ISSO must review audit trails periodically based on system documentation recommendations or immediately upon system security events.,Informational,"Dependent on organizational compliance. Application log entries are written to the container?s STDOUT, to be captured by the deployment?s preferred and compliant logging solution." +V-222623,The ISSO must report all suspected violations of IA policies in accordance with DoD information system IA procedures.,Informational,Dependent on organizational compliance. +V-222624,The ISSO must ensure active vulnerability testing is performed.,Informational,Dependent on organizational compliance. +V-222625,Execution flow diagrams and design documents must be created to show how deadlock and recursion issues in web services are being mitigated.,Not a Finding,"By design, the application web service is not subject to deadlocking as it does not call the client." +V-222626,The designer must ensure the application does not store configuration and control files in the same directory as user data.,Not a Finding,Application is provided as a stateless container. +V-222627,"The ISSO must ensure if a DoD STIG or NSA guide is not available, a third-party product will be configured by following available guidance.",Informational,Dependent on organizational compliance. Deployment and security guidance available in project documentation. +V-222628,"New IP addresses, data services, and associated ports used by the application must be submitted to the appropriate approving authority for the organization, which in turn will be submitted through the DoD Ports, Protocols, and Services Management (DoD PPSM)",Informational,Dependent on organizational compliance. +V-222629,The application must be registered with the DoD Ports and Protocols Database.,Informational,Dependent on organizational compliance. +V-222630,The Configuration Management (CM) repository must be properly patched and STIG compliant.,Informational,Configuration management dependent on organizational compliance and processes. Application code hosted on GitHub according to Code.mil guidance. +V-222631,Access privileges to the Configuration Management (CM) repository must be reviewed every three months.,Informational,"Configuration management dependent on organizational compliance and processes. Application code hosted on GitHub according to Code.mil guidance. Codebase access restricted to repository administrators, which are publicly listed on the project?s GitHub site." +V-222632,A Software Configuration Management (SCM) plan describing the configuration control and change management process of application objects developed by the organization and the roles and responsibilities of the organization must be created and maintained.,Informational,"Configuration management dependent on organizational compliance and processes. All project artifacts are publicly available on the GitHub site, in accordance with Code.mil guidance." +V-222633,"A Configuration Control Board (CCB) that meets at least every release cycle, for managing the Configuration Management (CM) process must be established.",Informational,"Configuration management dependent on organizational compliance and processes. All project artifacts are publicly available on the GitHub site, in accordance with Code.mil guidance." +V-222634,The application services and interfaces must be compatible with and ready for IPv6 networks.,Informational,Dependent on specific deployment. Web application is a Node.js application that includes support for IPv6. +V-222635,The application must not be hosted on a general purpose machine if the application is designated as critical or high availability by the ISSO.,Informational,Dependent on organizational compliance. +V-222636,A disaster recovery/continuity plan must exist in accordance with DoD policy based on the applications availability requirements.,Informational,Dependent on organizational compliance. +V-222637,Recovery procedures and technical system features must exist so recovery is performed in a secure and verifiable manner. The ISSO will document circumstances inhibiting a trusted recovery.,Informational,Dependent on organizational compliance. +V-222638,Data backup must be performed at required intervals in accordance with DoD policy.,Informational,Dependent on organizational compliance. +V-222639,Back-up copies of the application software or source code must be stored in a fire-rated container or stored separately (offsite).,Not a Finding,Application codebase is stored in a GitHub repository (offsite). +V-222640,Procedures must be in place to assure the appropriate physical and technical protection of the backup and restoration of the application.,Informational,Dependent on organizational compliance. +V-222641,The application must use encryption to implement key exchange and authenticate endpoints prior to establishing a communication channel for key exchange.,Informational,The project expects other layers to provide appropriate data protection via compliant cryptography. +V-222642,The application must not contain embedded authentication data.,Not a Finding,"No passwords, certificates, or sensitive data are included in the source code." +V-222643,The application must have the capability to mark sensitive/classified output when required.,Not a Finding,"The application interface indicates its configured classification, and all exports are marked with the configured classification." +V-222644,"Prior to each release of the application, updates to system, or applying patches; tests plans and procedures must be created and executed.",Not a Finding,Github workflows test functionality and access controls before release. +V-222645,Application files must be cryptographically hashed prior to deploying to DoD operational networks.,Not a Finding,The application is offered as containerized API/Web Client builds that are signed using Docker Content Trust. +V-222646,At least one tester must be designated to test for security flaws in addition to functional testing.,Not a Finding,"Automated feature and access control tests are run against every commit to the release branch. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Policy for more information." +V-222647,"Test procedures must be created and at least annually executed to ensure system initialization, shutdown, and aborts are configured to verify the system remains in a secure state.",Informational,Dependent on organizational compliance. +V-222648,An application code review must be performed on the application.,Informational,"SonarCloud scans, including OWASP tests and code reviews, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Policy for more information. Application source code is publicly available, and may be scanned at any time by any organization." +V-222649,Code coverage statistics must be maintained for each release of the application.,Informational,Code coverage assessed for development using Node.js c8 and newman tests. Reports available upon request. +V-222650,Flaws found during a code review must be tracked in a defect tracking system.,Informational,"All known code defects are tracked as Issues on the project?s GitHub site, or developer?s SonarCloud management page." +V-222651,The changes to the application must be assessed for IA and accreditation impact prior to implementation.,Informational,Dependent on organizational compliance. +V-222652,Security flaws must be fixed or addressed in the project plan.,Informational,"SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Policy page on GitHub for more info." +V-222653,The application development team must follow a set of coding standards.,Informational,"SonarCloud scans, including OWASP tests, and tests for coding standards, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Policy page on GitHub for more info." +V-222654,The designer must create and update the Design Document for each release of the application.,Informational,"Requires organizational compliance, project documentation, and project Security Policy." +V-222655,Threat models must be documented and reviewed for each application release and updated as required by design and functionality changes or when new threats are discovered.,Informational,"Requires organizational compliance, project documentation, and project Security Policy." +V-222656,The application must not be subject to error handling vulnerabilities.,Not a Finding,"Automated feature and access control tests are run against every commit to the release branch. SonarCloud scans, including OWASP tests, are run regularly to identify vulnerabilities. Manual testing also performed. See project Security Policy for more information." +V-222657,The application development team must provide an application incident response plan.,Not a Finding,See project documentation and Security Policy. +V-222658,All products must be supported by the vendor or the development team.,Not a Finding,Application is currently being actively maintained and supported. +V-222659,The application must be decommissioned when maintenance or support is no longer available.,Not a Finding,Application is currently being actively maintained and supported. +V-222660,Procedures must be in place to notify users when an application is decommissioned.,Informational,Dependent on organizational compliance. +V-222661,Unnecessary built-in application accounts must be disabled.,Not a Finding,Application has no built-in user accounts. Accounts are created and maintained by the OIDC provider. +V-222662,Default passwords must be changed.,Not a Finding,Application has no default passwords. +V-222663,An Application Configuration Guide must be created and included with the application.,Not a Finding,Project Documentation is provided. +V-222664,"If the application contains classified data, a Security Classification Guide must exist containing data elements and their classification.",Informational,Dependent on organizational compliance. +V-222665,The designer must ensure uncategorized or emerging mobile code is not used in applications.,Not a Finding,Application does not use uncategorized or emerging mobile code. +V-222666,Production database exports must have database administration credentials and sensitive data removed before releasing the export.,Informational,Dependent on organizational compliance. +V-222667,Protections against DoS attacks must be implemented.,Informational,Threat model dependent on organizational requirements. The project expects to be deployed in a Container Platform that resists DoS attacks. DoS mitigations expected to be implemented at Container Platform Ingress layer or otherwise fulfilled by specific deployment configurations. +V-222668,The system must alert an administrator when low resource conditions are encountered.,Informational,The project expects to be deployed in a Container Platform that monitors resource conditions. +V-222669,"At least one application administrator must be registered to receive update notifications, or security alerts, when automated alerts are available.",Informational,Dependent on organization compliance. Update notifications are available by subscription on GitHub project page. +V-222670,The application must provide notifications or alerts when product update and security related patches are available.,Not a Finding,Update notifications are available by subscription on GitHub project page. +V-222671,Connections between the DoD enclave and the Internet or other public or commercial wide area networks must require a DMZ.,Informational,Dependent on organizational compliance. +V-222672,The application must generate audit records when concurrent logons from different workstations occur.,Not a Finding,"When logging endpoint requests, the API emits audit records that include the original source IP address." +V-222673,"The Program Manager must verify all levels of program management, designers, developers, and testers receive annual security training pertaining to their job function.",Not a Finding,The Program Manager is subject to annual security training requirements. diff --git a/docs/source/install/db.rst b/docs/source/install/db.rst new file mode 100644 index 00000000..5d54c61d --- /dev/null +++ b/docs/source/install/db.rst @@ -0,0 +1,68 @@ +.. _db: + + +Database +######################################## + + +The C-PAT API was developed with a Controller-Service model that allows additional database services to be developed while using the same Controller code. However, the only database currently supported is MySQL. + + +Database User Requirements +----------------------------------- + +The database user specified must have sufficient permissions on the specified schema to update and create tables. +Specify the User and Schema with these environment variables: + + * ``CPAT_DB_SCHEMA`` + * ``CPAT_DB_USER`` + + + +.. _mySQL: + + +Database - MySQL 8.0.21+ +----------------------------- + +The C-PAT API is tested with the latest 3 minor versions of the MySQL 8.0.x series and 9.0.1 Innovation. +While C-PAT will bootstrap when provided with an 8.0.21+ MySQL database, it is strongly recommended you use the latest version of MySQL 8.0.x available. + +The API requires knowledge of 1) the DB address/port, 2) which schema (database) is used for C-PAT, and 3) User credentials with necessary privileges on that schema. `More information about MySQL. `_ + +.. note:: + The API includes a database migration function which tracks the database schema version and if necessary can automatically update the schema at launch. The initial run of the API scaffolds all database objects and static data. Releases that require a database change will include a message in the release notes. + + +Configure MySQL +~~~~~~~~~~~~~~~~~~~~ + +The C-PAT API requires a dedicated MySQL database (equivalent to a schema in other RDBMS products). The API connects to MySQL with an account that must have a full grant to the dedicated database but does not require server administration privileges. On first bootstrap, all database tables, views, and static data will be created. +Example commands to prepare MySQL for initial API execution: + + * Create database: ``CREATE DATABASE cpat`` + * Create API user account - ``CREATE USER 'cpat'@'%' IDENTIFIED BY 'new_password'`` + * Grant API user account all privileges on created database ``GRANT ALL ON cpat.* TO 'cpat'`` + +.. note:: + Suggested DB configuration options: + - ``sort_buffer_size`` - set to at least 2M (2097152), and perhaps up to 64M (Increasing the sort_buffer_size from the default of 256k may only be required if you have very large detail/comment text fields). + - ``innodb_buffer_pool_size`` - set to at least 256M (268435456), and perhaps up to 2GB (2147483648) + + +Configure C-PAT to use your MySQL Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Specify your MySQL DB with the following Environment Variables: + + * *CPAT_DB_HOST* - Default: localhost - The database hostname or IP from to the API server + * *CPAT_DB_PORT* - Default: 3306 - The database TCP port relative to the API server + * *CPAT_DB_USER* - Default: cpat - The user account used to login to the database + * *CPAT_DB_SCHEMA* - Default: cpat - The schema where the C-PAT object is found + * *CPAT_DB_PASSWORD* - The database user password. Not required if configuring TLS connections, as shown below. + +To enable TLS connections with your MySQL database, specify the following Environment Variables: + + * *CPAT_DB_TLS_CA_FILE* - A file/path relative to the API /tls directory that contains the PEM encoded CA certificate used to sign the database TLS certificate. Setting this variable enables TLS connections to the database. + * *CPAT_DB_TLS_CERT_FILE* - A file/path relative to the API /tls directory that contains the PEM encoded Client certificate used when authenticating the database client. + * *CPAT_DB_TLS_KEY_FILE* - A file/path relative to the API /tls directory that contains the PEM encoded Client private key used when authenticating the database client. \ No newline at end of file diff --git a/docs/source/install/environment-variables.rst b/docs/source/install/environment-variables.rst new file mode 100644 index 00000000..3570a507 --- /dev/null +++ b/docs/source/install/environment-variables.rst @@ -0,0 +1,21 @@ + +.. _Environment Variables: + +Environment Variables +========================= + +C-PAT is configured via its Environment Variables: + +.. csv-table:: C-PAT Environment Variables + :file: envvars.csv + :widths: 20, 70, 10 + :header-rows: 1 + :align: left + :class: tight-table + +.. csv-table:: Useful Node.js Environment Variables + :file: envvars-node.csv + :widths: 20, 70, 10 + :header-rows: 1 + :align: left + :class: tight-table diff --git a/docs/source/install/envvars-node.csv b/docs/source/install/envvars-node.csv new file mode 100644 index 00000000..eed935e2 --- /dev/null +++ b/docs/source/install/envvars-node.csv @@ -0,0 +1,2 @@ +"Variable","Description","Affects" +"NODE_EXTRA_CA_CERTS","**[your CA certificate file path]** Set this Node.js environment variable to direct Node to accept CA certificates you have provided, in addition to its built-in CA certs.","Node.js, API" diff --git a/docs/source/install/envvars.csv b/docs/source/install/envvars.csv new file mode 100644 index 00000000..58877c0d --- /dev/null +++ b/docs/source/install/envvars.csv @@ -0,0 +1,79 @@ +"Variable","Description","Affects" +"CPAT_API_ADDRESS","| **Default** ``127.0.0.1`` +| The IP address on which the the API server will listen ","API" +"CPAT_API_MAX_JSON_BODY","| **Default** ``52428800`` +| The maximum size in bytes of the request body when Content-Type is application/json","API" +"CPAT_API_MAX_UPLOAD","| **Default** ``52428800`` +| The maximum size in bytes of the file uploaded with Content-Type multipart/form-data","API" +"CPAT_API_RATE_LIMIT","| **Default** ``1000`` +| API rate limit per 15 minutes","API" +"CPAT_API_PORT","| **Default** ``8086`` +| The TCP port on which the server will listen ","API" +"CPAT_CLASSIFICATION","| **Default** ``U`` +| Sets the classification banner, if any. Available values: ``NONE`` ``U`` ``FOUO`` ``CUI`` ``C`` ``S`` ``TS`` ``SCI`` ","API, Client" +"CPAT_API_BASE","| **Default** ``api`` +| The base URL for Client requests to the API relative to the sever root at / ","Client" +"CPAT_CLIENT_DIRECTORY","| **Default** ``../client/dist`` +| The location of the web client files, relative to the API source directory. Note that if running source from a clone of the GitHub repository, the client is located at `../client/dist` relative to the API directory. ","API, Client" +"CPAT_CLIENT_DISABLED","| **Default** ``false`` +| Whether to *not* serve the reference web client","Client" +"CPAT_CLIENT_EXTRA_SCOPES","| **No default** +| OAuth2 scopes to request in addition to ``c-pat:read`` ``c-pat:write`` ``c-pat:op`` ``openid``. Some OIDC providers (Okta) generate a refresh token only if the scope ``offline_access`` is requested","Client" +"CPAT_CLIENT_ID","| **Default** ``c-pat`` +| The OIDC clientId for C-PAT","Client" +"CPAT_SCOPE_PREFIX","| **No default** +| String used as a prefix for each scope when authenticating to the OIDC Provider. Some providers (Azure AD) expect scope requests in the format ``api:///``, where ``api:///`` is the required prefix.","Client" +"CPAT_CLIENT_REFRESH_DISABLED","| **Default** ``false`` +| Whether the web client should use a provided refresh token to update the access token","Client" +"CPAT_DB_HOST","| **Default** ``localhost`` +| The database hostname or IP from to the API server","API" +"CPAT_DB_MAX_CONNECTIONS","| **Default** ``25`` +| The maximum size of the database connection pool ","API" +"CPAT_DB_USER","| **Default** ``cpat`` +| The user account used to login to the database ","API" +"CPAT_DB_PASSWORD","| **No default** +| The password used to login to the database ","API" +"CPAT_DB_PORT","| **Default** ``3306`` +| The database TCP port relative to the API server","API" +"CPAT_DB_SCHEMA","| **Default** ``cpat`` +| The schema where the C-PAT object is found","API" +"CPAT_DB_TLS_CA_FILE","| **No default** +| A file/path relative to the API /tls directory that contains the PEM encoded CA certificate used to sign the database TLS certificate. Setting this variable enables TLS connections to the database.","API" +"CPAT_DB_TLS_CERT_FILE","| **No default** +| A file/path relative to the API /tls directory that contains the PEM encoded Client certificate used when authenticating the database client. Additionally requires setting values for ``CPAT_DB_TLS_CA_FILE`` and ``CPAT_DB_TLS_KEY_FILE``. ","API" +"CPAT_DB_TLS_KEY_FILE","| **No default** +| A file/path relative to the API /tls directory that contains the PEM encoded Client private key used when authenticating the database client. Additionally requires setting values for ``CPAT_DB_TLS_CA_FILE`` and ``CPAT_DB_TLS_CERT_FILE``.","API" +"CPAT_DOCS_DIRECTORY","| **Default** ``./docs`` +| The location of the documentation files, relative to the API source directory. Note that if running source from a clone of the GitHub repository, the docs are located at `../../docs/_build/html` relative to the API directory. ","API, documentation" +"CPAT_DOCS_DISABLED","| **Default** ``false`` +| Whether to *not* serve the documentation.","Documentation" +"CPAT_LOG_LEVEL","| **Default** ``3`` +| Controls the granularity of the generated log output, from 1 to 4. Each level is inclusive of the ones before it. Level 1 will log only errors, level 2 includes warnings, level 3 includes status and transaction logs, and level 4 includes debug-level logs","API" +"CPAT_LOG_MODE","| **Default** ``combined`` +| Controls whether the logs will create one “combined” log entry for http requests that includes both the request and response information; or two separate log entries, one for the request and one for the response, that can be correlated via a generated Request GUID in each entry","API" +"CPAT_JWT_EMAIL_CLAIM","| **Default** ``email`` +| The access token claim whose value is the user's email address","API, Client" +"CPAT_JWT_FULL_NAME_CLAIM","| **Default** ``name`` +| The access token claim whose value is the user's full name","API, Client" +"CPAT_JWT_FIRST_NAME_CLAIM","| **Default** ``given_name`` +| The access token claim whose value is the user's first name","API, Client" +"CPAT_JWT_LAST_NAME_CLAIM","| **Default** ``family_name`` +| The access token claim whose value is the user's last name","API, Client" +"CPAT_JWT_PRIVILEGES_CLAIM","| **Default** ``realm_access.roles`` +| The access token claim whose value is the user’s privileges ","API, Client" +"CPAT_JWT_SCOPE_CLAIM","| **Default** ``scope`` +| The access token claim whose value is the user's scopes. Some OIDC Providers (Okta, Azure AD) use the claim ``scp`` to enumerate scopes","API, Client" +"CPAT_JWT_SERVICENAME_CLAIM","| **Default** ``clientId`` +| The access token claim whose value is the user's client","API, Client" +"CPAT_JWT_USERNAME_CLAIM","| **Default** ``preferred_username`` +| The access token claim whose value is the user's username","API, Client" +"CPAT_OIDC_PROVIDER","| **Default** ``http://localhost:8080/auth/realms/RMFTools`` +| The base URL of the OIDC provider issuing signed JWTs for the API. The string ``/.well-known/openid-configuration`` will be appended when fetching metadata.","API, Client" +"CPAT_CLIENT_OIDC_PROVIDER","| **Default** ``CPAT_OIDC_PROVIDER`` +| Client override of the base URL of the OIDC provider issuing signed JWTs for the API. The string ``/.well-known/openid-configuration`` will be appended when fetching metadata.","API, Client" +"CPAT_SWAGGER_ENABLED","| **Default** ``false`` +| Whether to enable the SwaggerUI SPA at /api-docs ","API" +"CPAT_SWAGGER_REDIRECT","| **Default** ``http://localhost:8086/api-docs/oauth2-redirect.html`` +| The redirect URL sent by SwaggerUI to the OIDC provider when authorizing","API" +"CPAT_SWAGGER_SERVER","| **Default** ``http://localhost:8086/api`` +| The API server URL relative to the SwaggerUI ","API" diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst new file mode 100644 index 00000000..fd6772d0 --- /dev/null +++ b/docs/source/install/index.rst @@ -0,0 +1,27 @@ + +.. _installation-index: + +Setup and Deployment +=============================== + +.. meta:: + :description: Deploying C-PAT. + +These pages describe how to setup and deploy C-PAT + + + +.. toctree:: + :maxdepth: 2 + :numbered: 4 + :caption: Contents: + + installation + authentication + db + logging + reverse-proxy + environment-variables + securing + integrations + diff --git a/docs/source/install/installation.rst b/docs/source/install/installation.rst new file mode 100644 index 00000000..cd3f2fa3 --- /dev/null +++ b/docs/source/install/installation.rst @@ -0,0 +1,270 @@ + +.. _installation-and-setup: + +C-PAT Setup and Technical Information +########################################################## + +C-PAT is an open-source project that provides an API and Web Client. The project is ideal for a containerized deployment but can also be run from source code in a Node.js runtime environment. + +Several deployment approaches are described in this document: + +- :ref:`Deploy from individual Docker Containers ` +- :ref:`Deploy from Source Code in Node.js runtime environment ` + + +A C-PAT deployment requires two other mandatory services, which are freely available but must be provided and configured by the those deploying the C-PAT instance: + - An OpenID Connect (OIDC) Provider + - A MySQL database + +C-PAT offers an additional container that provide a "starter" keycloak deployment that could be used as a point of reference for production deployments: + - Our `RMF Tools Keycloak Container `_ offers a pre-configured demonstration configuration of Keycloak that provides the necessary clients, scopes, and roles for C-PAT and `STIG Manager `_. + +C-PAT is architected to be deployed at the enterprise level with orchestration platforms such as Kubernetes or OpenShift. However, containerization allows C-PAT deployments to be readily scaled up or down and it can be orchestrated on a single laptop with tools such as docker-compose. + +.. note:: + Containerized deployments of C-PAT are highly recommended because they offer improved security, scalability, portability, and maintenance, but they are not required. It is entirely possible to deploy C-PAT and some or all supporting applications in a traditional manner from source code. In almost all cases, the same configuration options documented here would apply. + + +Common Components +================= + +Required and optional components of a C-PAT deployment: + +**API** (Always Required) + A RESTful API implemented on the current LTS version of Node.js and the Express web application framework. Exposes 1 HTTP port. Built as a stateless container service. +**Web Client** (Recommended for Interactive Access) + A Single Page Application (SPA) using the Angular framework. The Web Client is served from the API container and does not require a separate container. +**OIDC Provider** (Always Required) + An authentication service that manages user accounts and issues OAuth2 JWT tokens to the Web Client which authorize access to the API. Keycloak has been thoroughly tested and selected as the provider of choice, however, limited testing has been done using authentication services from Okta and Azure AD. +**MySQL Database** (Always Required) + A stateful data storage capability that supports mutual TLS authentication and secure data at rest. + + +.. note:: + The C-PAT API itself is stateless, and persists no data. All application data is stored in the deployer-provided MySQL database. Responsibility for data security and backup is entirely the responsibility of the deployer maintaining the database. + Likewise, the OIDC Provider is responsible for user authentication and authorization, and the deployer is responsible for the security and backup of the OIDC Provider. + + +------------------------------- + + +Deployment Scenarios +=============================================== + +.. _deploy-container: + +Container Deployment with Docker +------------------------------------------------- + +Using the C-PAT container image is the recommended way to deploy C-PAT. + +Requirements +~~~~~~~~~~~~~~ + +- `Docker `_ +- :ref:`OIDC Authentication Provider ` +- :ref:`mySQL` + + +Procedure +~~~~~~~~~~~~~~~~~~~~~ + +#. Install Docker +#. Install and configure the Authentication and Database requirements. Sample configuration instructions for these requirements can be found here: + + - :ref:`keycloak` + - :ref:`mySQL` + + *Make note of the address and ports these servers are using (as well as any other values that differ from the defaults). Set the appropriate* :ref:`Environment Variables` *to these values so C-PAT can reach them.* + +#. Pull the latest image from Docker Hub. This command will grab the latest stable image: ``docker pull nswccrane/c-pat:latest`` +#. Run the C-PAT image using the ``docker run`` command. Specify Environment Variables if the defaults in the :ref:`Environment Variables` reference do not work for your environment. Set the Environment Variables using ``-e =`` parameters. A sample docker run command, exposing port 8086, and creating a container named "c-pat" is shown here: + + .. code-block:: bash + + docker run --name c-pat -d \ + -p 8086:8086 \ + -e CPAT_DB_HOST= \ + -e CPAT_DB_PORT= \ + -e CPAT_OIDC_PROVIDER=http://:/auth/realms/RMFTools \ + nswccrane/c-pat + + +#. Check the logs by running ``docker logs`` to verify successful startup. Sample log entries showing the end of a successful startup are shown below. Check the :ref:`logging` reference for more detailed information. + + .. code-block :: bash + + [START] Checking classification... + [START] Server is listening on port 8086 + [START] API is available at /api + [START] API documentation is available at /api-docs + [START] Client is available at / + + +.. _deploy-source: + +Deployment from Source Code +------------------------------- + +C-PAT can be deployed from source if the proper Node.js runtime is provided. These instructions relate to a Windows deployment, however, C-PAT can be run anywhere Node.js is available. + + +Requirements +~~~~~~~~~~~~~~ + +- `Node.js LTS `_ +- :ref:`OIDC Authentication Provider ` +- :ref:`mySQL` +- `git `_ *(recommended)* + + +Procedure +~~~~~~~~~~~~~~~~~~~~~ + + +#. Install Node.js +#. Install and configure the Authentication and Database requirements. Sample configuration instructions for these requirements can be found here: + + - :ref:`keycloak` + - :ref:`mySQL` + + *Make note of the address and ports these servers are using (as well as any other values that differ from the defaults). Set the appropriate* :ref:`Environment Variables` *to these values so C-PAT will be able to reach them.* + +#. Using git, Clone the repository. ``git clone https://github.com/NSWC-Crane/C-PAT.git`` +#. Navigate to the ``/api`` directory in the project folder. +#. From within the ``/api`` directory, open or create the .env file. Set the Environment Variables as appropriate for your environment. An example can be found on `GitHub `_. +#. Run one of the following commands: + - ``npm run install``. This command will download the required packages for the client and API, build the client files, and start the API which dynamically serves the client. + - ``npm run start``. This command will start the API which dynamically serves the client. + - ``npm run offline-rebuild``. This command will build the client files and start the API which dynamically serves the client. + +.. note:: + When running from source, the client files are located at ``../client/dist`` relative to the API directory. If these files are moved, set the ``CPAT_CLIENT_DIRECTORY`` environment variable as appropriate. + + +Updating C-PAT +------------------------------------------------- + +Because C-PAT itself is stateless, updates are relatively simple. Follow the same procedure as the initial deployment, but with the updated version of the app, configured to use the same OIDC and database resources. + +Some releases may require database schema changes. In these cases, the app will automatically apply the necessary changes to the database schema when it starts up. These changes can occasionally take several minutes to run if your data set is large. We note these "Database Migrations" in our Release Notes. We recommend updates be performed during a maintenance window, and that a current database backup is available. + +Most updates do not require database migrations. + +Downgrading C-PAT to an earlier version is not supported. If you need to revert to an earlier version, you will need to restore the database from a backup taken with the earlier version. + +| + +Common Configuration Variables +------------------------------------------------- +The API and Web Client are configured using :ref:`Environment Variables`. They neither require nor use a configuration file. + +It is likely you will have to set at least some of these Environment Variables, but check the full :ref:`Environment Variables` reference for the full list: + + * Database-related: + + - CPAT_DB_ACQUIRE + - CPAT_DB_DIALECT + - CPAT_DB_HOST + - CPAT_DB_IDLE + - CPAT_DB_PORT + - CPAT_DB_SCHEMA + - CPAT_DB_PASSWORD (unless using TLS for authentication) + - CPAT_DB_USER + - CPAT_DB_MAX_CONNECTIONS + - CPAT_DB_MIN_CONNECTIONS + - CPAT_DB_TLS_CA_FILE + - CPAT_DB_TLS_CERT_FILE + - CPAT_DB_TLS_KEY_FILE + - CPAT_DB_REVERT + - CPAT_DB_TLS_CA_FILE + - CPAT_DB_TLS_CERT_FILE (unless using password for authentication) + - CPAT_DB_TLS_KEY_FILE (unless using password for authentication) + + * Authentication-related: + + - CPAT_OIDC_PROVIDER + + * Advanced Authentication-related: + + - CPAT_EXTRA_SCOPES + - CPAT_SCOPE_PREFIX + - CPAT_JWT_USERNAME_CLAIM + - CPAT_JWT_SERVICENAME_CLAIM + - CPAT_JWT_FIRST_NAME_CLAIM + - CPAT_JWT_LAST_NAME_CLAIM + - CPAT_JWT_FULL_NAME_CLAIM + - CPAT_JWT_PRIVILEGES_CLAIM + - CPAT_JWT_EMAIL_CLAIM + + * General Configuration: + + - CPAT_API_ADDRESS + - CPAT_API_PORT + - CPAT_CLASSIFICATION + + * Swagger OpenAPI Tool Configuration: + + - CPAT_SWAGGER_ENABLED + - CPAT_SWAGGER_SERVER + - CPAT_SWAGGER_REDIRECT + +Additional Suggested Configuration +======================================= + + +Enable Extra CA Certificates +---------------------------------------- +Set the ``NODE_EXTRA_CA_CERTS=file-path`` Node.js environment variable to direct Node to accept CA certificates you have provided, in addition to its built-in CA certs. + +Check the `Node.js documentation for more information. `_ + + +Configure Logging +----------------------- +:ref:`Store logs according to Organization requirements. ` + +First Steps +============== + +.. index:: + single: Add Users + +.. _Adding Users: +.. _Add Users: +.. _user-roles-privs: + +Configure Users +-------------------------- + +Users are not created in C-PAT itself. All users must be authenticated by your Authentication Provider (Keycloak, Okta, etc) and be assigned the appropriate roles and scopes before they can obtain a token that is required to access the system. Upon first access after successful Authentication, C-PAT will create a user profile with a PENDING status. + +User privileges are controlled by the Authentication Provider. This can be done by configuring and assigning Users the appropriate roles. In Keycloak, this can be done using the "Role Mappings" tab for that user, or you can set these roles as defaults using the Configure->Roles->Default Roles interface. See the :ref:`Authentication and Identity` section for more information. + +Assign at least one User the ``admin`` role when setting up C-PAT for the first time. + +.. list-table:: C-PAT User Types, C-PAT Privileges, and suggested Roles: + :widths: 20 60 20 + :header-rows: 1 + :class: tight-table + + * - User Type + - Privileges + - Roles + * - C-PAT Administrator + - Access C-PAT, Manage Users, Manage Collections, Set Global A&A Package name options, Import/Export collection data. + - admin, cpat_write, user + * - Standard User + - Access C-PAT, create POAMs, create assets, create labels. + - cpat_write, user + * - Restricted User + - Access C-PAT, limited functionality, view only. + - user + +.. note:: + All Users must be explicitly granted access to specific collections in order to see data contained therein. Administrators can grant themselves or others access to any Collection from within the User Management tab inside the Administrative Portal. + +It is recommended that most users should be "Standard Users" (ie. assigned the "user" and "cpat_write" roles). A Restricted User will only have access to view limited amounts of data and will not be able to create or modify any data. + +C-PAT further provides the ability to assign collection permissions for authenticated users. Specific permissions to Collections are managed in User Management tab of the Administrative Portal. Users can be assigned to one or more collections, and given "Viewer", "Submitter", "Approver", or "CAT-I Approver" permissions. + diff --git a/docs/source/install/integrations.rst b/docs/source/install/integrations.rst new file mode 100644 index 00000000..0d59f44e --- /dev/null +++ b/docs/source/install/integrations.rst @@ -0,0 +1,59 @@ +.. _integrations: + + +Integrations Configuration +######################################## + + +C-PAT offers integrations with `STIG Manager `_ and `Tenable.sc `_. +While it is possible to run C-PAT independently, to fully realize the benefits of C-PAT it is **strongly** recommended that C-PAT be configured to run in conjunction with these tools. + + +STIG Manager +--------------- +.. note:: + C-PAT has been tested and configured to work when C-PAT and STIG Manager are housed within the same OIDC realm, therefor, the value set for ``CPAT_OIDC_PROVIDER`` will also be used for obtaining a token for STIG Manager. + If you are using the provided `RMFTools Keycloak container `_, the default value for ``STIGMAN_OIDC_CLIENT_ID`` can be used. + +.. list-table:: STIG Manager Environmenment Variables: + :widths: 20 25 55 + :header-rows: 1 + :class: tight-table + + * - Variable + - Default + - Description + * - ``STIGMAN_OIDC_CLIENT_ID`` + - stig-manager + - The OIDC clientId for STIG Manager. + * - ``STIGMAN_API_URL`` + - http://localhost:54000/api + - The URL to the STIG Manager API. + * - ``STIGMAN_SCOPE_PREFIX`` + - **No default** + - String used as a prefix for each STIG Manager scope when authenticating to the OIDC Provider. This will likely match your ``STIGMAN_CLIENT_SCOPE_PREFIX`` environment variable configured in STIG Manager (if applicable). + * - ``STIGMAN_EXTRA_SCOPES`` + - **No default** + - Scopes to request in addition to: ``stig-manager:stig`` ``stig-manager:stig:read`` ``stig-manager:collection`` ``stig-manager:user`` ``stig-manager:user:read`` ``stig-manager:op`` ``openid`` + + +Tenable +------ + + .. list-table:: Tenable Environmenment Variables: + :widths: 20 25 55 + :header-rows: 1 + :class: tight-table + + * - Variable + - Default + - Description + * - ``TENABLE_URL`` + - **No default** + - The URL to your instance of Tenable.sc, no trailing slashes or additional paths are necessary. Example: ``https://myACASinstance.something.com`` + * - ``TENABLE_ACCESS_KEY`` + - **No default** + - See the `tenable documentation `_ for instructions on how to generate API keys. + * - ``TENABLE_SECRET_KEY`` + - **No default** + - See the `tenable documentation `_ for instructions on how to generate API keys. \ No newline at end of file diff --git a/docs/source/install/logging.rst b/docs/source/install/logging.rst new file mode 100644 index 00000000..e7f4f31a --- /dev/null +++ b/docs/source/install/logging.rst @@ -0,0 +1,114 @@ +.. _logging: + + +Logging +######################################## + + +C-PAT streams structured JSON logging objects to standard output (STDOUT). +You should capture and persist these logging objects in accordance with your Organizational requirements. + + +Logging schemas +--------------- + +The full JSON Schema of our logging objects is available here. This documentation is organized to describe each +logging component separately and presents the relevant sub-schemas. + +Common +------ + +.. tabs:: + + .. code-tab:: json + + { + "$schema": "https://json-schema.org/draft-07/schema", + "$id": "http://yourdomain.com/schemas/myschema.json", + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date-time" + }, + "level": { + "type": "integer", + "minimum": 1, + "maximum": 4 + }, + "component": { + "type": "string", + "enum": [ + "index", + "initData", + "oidc", + "mysql", + "static", + "rest", + "logger" + ] + }, + "type": { + "type": "string" + }, + "data": { + "type": "object" + } + }, + "required": [ + "date", + "level", + "component", + "type", + "data" + ], + "additionalProperties": false + } + + .. code-tab:: yaml + + "$schema": https://json-schema.org/draft-07/schema + "$id": http://yourdomain.com/schemas/myschema.json + type: object + properties: + date: + type: string + format: date-time + level: + type: integer + minimum: 1 + maximum: 4 + component: + type: string + enum: + - index + - initData + - oidc + - mysql + - static + - rest + - logger + type: + type: string + data: + type: object + required: + - date + - level + - component + - type + - data + additionalProperties: false + + +The ``data`` object is extensible and will contain structured details concerning the event. + +The contents of the logs can be controlled with the following :ref:`Environment Variables`: + +CPAT_LOG_LEVEL + - Default: ``3`` + - Controls the granularity of the generated log output, from 1 to 4. Each level is inclusive of the ones before it. Level 1 will log only errors, level 2 includes warnings, level 3 includes status and transaction logs, and level 4 includes debug-level logs. + +CPAT_LOG_MODE + - Default: ``combined`` + - Controls whether the API will create one "combined" log entry for http requests that includes both the request and response information; or two separate log entries, one for the request and one for the response, that can be correlated via a generated Request GUID in each entry. Any value other than "combined" will produce separate log entries. diff --git a/docs/source/install/reverse-proxy.rst b/docs/source/install/reverse-proxy.rst new file mode 100644 index 00000000..63f32ac4 --- /dev/null +++ b/docs/source/install/reverse-proxy.rst @@ -0,0 +1,58 @@ +.. _reverse-proxy: + + +Deploy with TLS +######################################## + + + +Configure a Reverse Proxy or Kubernetes Ingress Controller +======================== + +To support HTTPS connections, C-PAT components should be situated behind a reverse proxy or in a Kubernetes cluster. Configure the reverse proxy (such as nginx) or the Kubernetes Ingress Controller in accordance with publisher documentation, local security requirements, and Keycloak documentation. +In either case, you will have to set Keycloak environment variable `PROXY_ADDRESS_FORWARDING=true` and make sure appropriate headers are forwarded. + + + +Nginx for TLS +======================== + +C-PAT provides two branches on GitHub with sample RMF Tools nginx deployments with a configuration file that may be useful to those setting up a Production deployment of C-PAT and STIG Manager: + + + +With CAC Authentication +------------------------------------------ + +https://github.com/NSWC-Crane/C-PAT/tree/rmftools-orchestration-cac + + + +Without CAC Authentication +------------------------------------------ + +https://github.com/NSWC-Crane/C-PAT/tree/demo-auth-no-CAC + + + +------------------------------------------ + +.. thumbnail:: /assets/images/component-diagram.svg + :width: 50% + :show_caption: True + :title: Component Diagram with Reverse Proxy + +--------------------------- + +.. thumbnail:: /assets/images/k8-component-diagram.svg + :width: 50% + :show_caption: True + :title: Component Diagram with Kubernetes + + +| +| + + + + diff --git a/docs/source/install/securing.rst b/docs/source/install/securing.rst new file mode 100644 index 00000000..3bcd0e54 --- /dev/null +++ b/docs/source/install/securing.rst @@ -0,0 +1,129 @@ +.. _securing: + + +Securing and Assessing C-PAT Deployments +########################################################## + +.. warning:: + You must secure and assess your deployments in compliance with your individual or organizational security requirements. The discussions below are educational. Encouragement to do things a particular way does not constitute advice that overrides your specific requirements. + + +C-PAT can be orchestrated several ways, each with unique security requirements. We know many deployments must comply with the Application Security and Development STIG - commonly known as the ASD. Therefore we have organized this section around ASD requirements, to provide guidance for those tasked with securing and assessing STIG-compliant C-PAT deployments. + +.. note:: + The ASD assesses many application components, and application governance, using a single checklist of 286 checks (as of V5R1). Unfortunately, the current ASD provides limited guidance if you're using modern security technologies such as Single Sign On, OpenID Connect, OAuth2 authorization, and containerization. If you are required to complete an ASD assessment, we encourage focusing on the spirit of the checklist until it is updated or re-imagined. + +Securing Your Deployment +======================== + +These are some common security topics to review when designing a secure C-PAT application deployment. + +Container Security +------------------ + +We strongly encourage C-PAT deployments to be containerized. Containerization has built-in security advantages such as immutability, image signing, transparency, modularity, small attack surface, secure updates, and environment parity. The content of container images and their runtime behavior require security evaluations, as in traditional deployments, but provide the advantage of image layer inheritance. + +.. note:: + If you are subject to ASD-compliance you are likely subject to other DoD requirements. We encourage an in-depth familiarity with the `Container Image Creation and Deployment Guide `_ from DISA. C-PAT adheres to DISA image creation guidance when defining and building container images, and we encourage C-PAT deployments to follow the container deployment guidance. + + +Data Flow +--------- + +Several ASD checks refer to SOAP, WS-Security and SAML, early protocols for implementing and securing online APIs. None of the checks refer to REST or OIDC/OAuth2, modern alternatives that are commonly used in cloud-ready software such as C-PAT. The checks that address SOAP, etc. state that if you aren't using those technologies, the assessment is 'not applicable'. + +.. note:: + The discussion below assumes the reader has prerequisite knowledge of REST principles, `OAuth2 flows as defined in RFC 6749 `_ and the `Open ID Connect Core 1.0 specification `_ + +| + +REST and OpenAPI Specification (OAS) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The C-PAT API and Web Client exchange data across a REST architecture that enforces the C-PAT Manager `OAS definition `_. + +Access to individual endpoints is controlled by the OAuth2 ``scope`` claims listed in each endpoint's ``security.oauth`` property in the OAS. Oauth2 is discussed further below. + +Discretionary Access Control (DAC) and Role Based Access Control (RBAC) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The C-PAT API grants or denies access to data objects (Collections, POAMs, Assets) based on the the OAuth2 ``username`` claim. The username value is cross referenced during the internal permission validation to obtain the access a user is assigned within the collection they are requesting data from(if applicable), in addition to validating the provided token contains the scope necessary for the request. As a further step of validation, the C-PAT client is also configured to obtain the users access level and dynamically disable routes and components that the user does not have access to based upon the permissions assigned within the Apministrative Portal, User Management tab. + + +OpenID Connect (OIDC) and OAuth2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The claims described in the sections above are contained in OAuth2 JWT formatted access_tokens issued by an OIDC Provider to remote clients. + +On startup, the web client redirects users to the OIDC Provider to authenticate and obtain an access token that defines the scope of API access. For most ASD-compliant deployments, the connection to the OIDC Provider's authorization_endpoint will use MTLS and CAC PKI. + +.. note:: + Communication between the API and clients include the access_token and should occur using TLS but do not require Mutual TLS (MTLS). + +The Web Client is a single-page application (SPA) that executes entirely in the browser. Browsers are low- to zero-trust environments where OAuth2 access tokens should have short lifetimes to mitigate the risk of token diversion. What is considered 'short' is for you (or your organization) to decide, but 15 minutes or even less is not uncommon. + +The Web Client will not engage in an OIDC implicit flow. The OIDC Provider must provide tokens using the OIDC Authorization Code Flow with Proof Key for Code Exchange (PKCE). + +If your OIDC Provider issues refresh tokens (highly encouraged for a better user experience), those tokens usually have longer lifetimes than the access_token but should be rotated and limited to a single use. Policies vary greatly, but refresh token lifetime is sometimes correlated to the SSO session lifetime. Attempts to reuse a refresh_token should be logged by the OIDC Provider and generate alerts. + +User Sessions +------------- + +.. note:: + The discussion below assumes the reader has knowledge of their specific OIDC Provider and any user federation or identity brokering features it is configured to use. + +Several ASD checks address the management of user login sessions. It is important to understand how your OIDC Provider controls user sessions, performs user management, and audits its activities. + +Database +-------- + +.. note:: + The discussion below assumes the reader has prerequisite knowledge of MySQL and how to perform PKI user authentication (if required), secure data storage, and secure data backups. + +Several ASD checks address the management of data storage. It is important to understand how to configure MySQL in accordance with local security requirements, such as the Oracle MySQL 8.0 STIG. Ideally, your organization will provision MySQL instances from a hardened cloud subscription that requires a smaller set of customer-responsible security settings. + +Logging and Analysis +----------------------- + +Many ASD checks specify requirements for how application log entries should collected, aggregated, managed, audited, and analysed. The C-PAT application role in this is simple: it outputs all its log entries to STDOUT. These log entries must be captured and retained in accordance with your log retention policy. C-PAT has made efforts to ensure that the logs the application emits conform to requirements specified in the ASD where appropriate. However, there are several other components of a successful deployment that will produce logs that may also require management by your logging solution, such as the OIDC Provider, Database, and Container Platform. + +Transport Layer Security +--------------------------- + +The ASD specifies the use use of TLS-secured connections to the application. To meet this requirement, we strongly encourage deploying application components behind a reverse proxy that provides this capability. The reverse proxy should be able to handle many ASD requirements, such as TLS authentication, use of DoD Common Access Cards (CAC), and TLS encryption for the API, Web Client, and OIDC Provider. + + +Assessing Your Deployment +============================= + +The documentation and artifacts provided here are intended to help teams that are deploying C-PAT in an environment that is subject to the Application Security and Development STIG. Below you can find a summary relevant to this effort. + +Where applicable, we have self-evaluated portions of the ASD **as if** we were developer members of a deployed application's team. For most deployments, though, we are NOT part of your team and therefore the checks covering development practices might be properly evaluated as not applicable. Even in this case, however, we hope our self-evaluation provides useful insight into how C-PAT integrates security into our practice. + +API and Web Client +------------------ + +About a third of the checks in the ASD assess application components provided by C-PAT - the API and Web Client. These checks assess both their behavior and how they are developed. All other checks are dependent on specific deployment configurations, but we have provided some guidance where we can. + + +.. warning:: + You must evaluate your deployment independently in accordance with your individual security requirements. Our self-evaluation CANNOT and DOES NOT represent a valid assessment of your deployment! + + +It is always possible to configure your deployment into an insecure state. +The provided assessments may not apply to the way you have configured your deployment! They are to be used only as a guide or as reference for your own assessments. In general, we have followed this convention when providing assessments: + + - Reviews are marked **Not a Finding** if they are considered by the C-PAT team to be compliant with the ASD by nature of the design and practices executed by the developers. + + - Reviews are marked **Not Applicable** only if the project design meets conditions provided in rule guidance. It is always possible that your deployment configuration makes that particular STIG check "applicable." + + - Reviews marked **Informational** or **Not Reviewed** may have useful details to be used as reference for assessments but cannot be satisfied by the project application alone. + + +.. csv-table:: Application Security and Development STIG Self Assessment + :file: cpat-asd-full.csv + :widths: 10, 25, 10, 25 + :header-rows: 1 + :stub-columns: 1 + :align: left + :class: tight-table \ No newline at end of file diff --git a/docs/source/user/assetprocessing.rst b/docs/source/user/assetprocessing.rst new file mode 100644 index 00000000..b0a1815a --- /dev/null +++ b/docs/source/user/assetprocessing.rst @@ -0,0 +1,28 @@ +.. _assetprocessing: +Asset Processing +---------------- + +The asset processing component is responsible for displaying all assets pertaining to a specific collection. The following section is seperated into 3 parts; local assets, STIG Manager Assets, and Tenable Assets. +Each section contains global functionality to reduce or add columns to the table view and export the asset table data to a .csv file. + +Local Assets +^^^^^^^^^^^^ +When a user is browsing a collection that belongs organically to C-PAT, i.e. the collection was created in C-PAT and not imported from Tenable or STIG Manager, the Asset Processing component will display the local assets view. +The local assets view contains a tabset with 2 tabs, Asset Management and Asset Chart. + +The asset management tab displays a table of all assets in the collection with filterable columns for Asset ID, Asset Name, Description, IP Address, and MAC Address. To add an asset to the collection, click "Add Asset" and complete the pop-up form. After an asset is added, it will become an available option to select when manually adding assets to a POAM. + +To modify an asset, a user has two options. + 1. Clicking the row of the asset in the table. + 2. Selecting the asset from the dropdown menu located below the table. + +Either option will open a pop-up form with the asset's information. The user can modify the asset's information and click "Save" to save the changes. + +STIG Manager Assets +^^^^^^^^^^^^^^^^^^^ +The STIG Manager Assets view is displayed when a user is browsing a collection that was imported from STIG Manager. The STIG Manager Assets view contains a single assets table with columns for Asset Name, FQDN, IP Address, MAC Address, Collection Name, and STIG Manager Labels. The table is a display of assets returned from a query to the STIG Manager API at ``/assets?collectionId={collectionId}`` and contains data that is current as of the time that the user opens the Asset Processing component. + + +Tenable Assets +^^^^^^^^^^^^^^ +The Tenable Assets view is displayed when a user is browsing a collection that was imported from Tenable. The Tenable Assets view contains a single assets table with columns for Plugin ID, Name, Family, Severity, VPR, IP Address, ACR, AES, NetBIOS, DNS, MAC Address, Port, Protocol, Agent ID, and Host ID. The table is a display of assets returned from a query to the Tenable API at ``/analysis`` using the ``listvuln`` tool with a filter for ``repository`` to match the collection that the user is currently viewing. The asset data displayed is current as of the time that the user opens the Asset Processing component. \ No newline at end of file diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst new file mode 100644 index 00000000..9178cabe --- /dev/null +++ b/docs/source/user/index.rst @@ -0,0 +1,25 @@ + +.. _admin-index: + +User Guide +=============================== + +.. meta:: + :description: C-PAT features. + +These pages describe the features contained in C-PAT. + + +.. toctree:: + :maxdepth: 2 + :numbered: 4 + :caption: Contents: + + poamcreation + poamexporting + manage-poams + stigman + tenable + assetprocessing + labelprocessing + diff --git a/docs/source/user/labelprocessing.rst b/docs/source/user/labelprocessing.rst new file mode 100644 index 00000000..33f963a6 --- /dev/null +++ b/docs/source/user/labelprocessing.rst @@ -0,0 +1,13 @@ +.. _labelprocessing: +Label Processing +---------------- + +The Label Processing component contains the functionality to add labels within a collection. Labels can then be added to a POAM in step 9 of the POAM workflow. Labels are viewable in charts across C-PAT and serve as a quick and easy way to tag and identify POAMs that may have unique features or that may fall within the purview of a specific individual or group for action. + +Labels can be added to a collection by selecting the "Add Label" button located beneath the labels table. This will open a modal window where the user can input a label name and description. Once the label is created, it will be added to the labels table and can be selected for use in the POAM workflow. + +To modify a label, a user has two options. + 1. Clicking the row of the label in the table. + 2. Selecting the label from the dropdown menu located below the table. + +Either option will open a pop-up form with the labels information. The user can modify the labels information and click "Save" to save the changes. \ No newline at end of file diff --git a/docs/source/user/manage-poams.rst b/docs/source/user/manage-poams.rst new file mode 100644 index 00000000..16964c91 --- /dev/null +++ b/docs/source/user/manage-poams.rst @@ -0,0 +1,49 @@ +.. _manage-poams: +Manage POAMs +------------ + +The Manage POAMs component is a compilation of charts, tables, and grids that are ultimately designed to assist a user in quickly and easily identifying the data they want or need to view. The Manage POAMs component is broken down into the following interactive sections: POAM Status Grid (tabset), Main POAM Chart, and the Main POAM Chart expansion table. + +POAM Main Chart +^^^^^^^^^^^^^^^ + +The POAM Main Chart contains a single dataset that is seperated into 4 different viewing formats; POAM Status, Severity, Scheduled Completion, and Labels. Each section is filterable via the filter dropdown located below the chart. +Filters are available for Status, Severity, Scheduled Completion, Labels, and Vulnerability Source. Multiple filters can be applied. + +POAM Expanded Grid +^^^^^^^^^^^^^^^^^^ + +The expanded POAM grid is a table that dynamically reflects the POAMs from the POAM Main Chart. When the main chart is filtered, the resulting data displayed in the expanded grid will also be filtered. In addition to the filters available in the Main Chart, the expanded POAM grid also contains column filters for the following fields: +Last Updated, POAM ID, Vulnerability ID, POAM Status, Vulnerability Source, STIG Benchmark, Adjusted Severity, Submitter, Assigned Teams, Submitted Date, and Scheduled Completion Date. + +The far right column of the expanded POAM grid contains an icon that will direct users to the POAM details page for further information. + +.. note:: + POAM's are also exportable from within the expanded grid. The export will contain all POAMs displayed in the grid, formatted into the eMASS excel format. + +Assigned Grid +^^^^^^^^^^^^^ + +The Assigned Grid is a table that displays POAMs segmented into one of four seperate categories; All POAMs, Needs Attention, My POAMs, and Pending Approval. + +.. note:: + The tabs contained within the Assigned Grid are displayed based upon a users assigned permissions within a collection. To see all 4 tabs, a user must be assigned to an access level 3 or higher (Approver). + + +All POAMs +""""""""" +The All POAMs tab displays all POAMs that are currently available within the collection. No filtering is conducted on the dataset for the All POAMs tab. Access Level of 1 (Viewer) or greater is required to view this tab. + + +Needs Attention +""""""""""""""" +The Needs Attention tab contains POAMs where the Scheduled Completion Date is less than 30 days and the POAM status is not Draft, Closed, or False Positive. Access Level of 1 (Viewer) or greater is required to view this tab. + + +My POAMs +"""""""" +The My POAMs tab displays all POAMs that have been submitted by the user where the POAM status is not Closed. Access Level of 2 (Submitter) or greater is required to view this tab. + +Pending Approval +"""""""""""""""" +The Pending Approval tab displays all POAMs that are Pending Approval within the current collection [POAM Status of Submitted, Extension Requested, or Pending CAT-I Approval]. Access Level of 3 (Approver) or greater is required to view this tab. diff --git a/docs/source/user/poamcreation.rst b/docs/source/user/poamcreation.rst new file mode 100644 index 00000000..177bef2d --- /dev/null +++ b/docs/source/user/poamcreation.rst @@ -0,0 +1,113 @@ +.. _poamcreation: + +POAM Creation +------------- + +Manual POAM Entry +^^^^^^^^^^^^^^^^ +While not recommended, POAMs can be created manually: + + 1. All fields must be entered by the user + 2. Assets must be selected manually from the collection's asset list + 3. Requires more validation and verification + +STIG Manager Integration +^^^^^^^^^^^^^^^^^^^^^^^^ +When creating a POAM from STIG Manager findings: + +1. C-PAT automatically populates: + + * Description from STIG check + * Vulnerability Source (set to "STIG") + * STIG Title and Benchmark ID + * Vulnerability ID + * Raw Severity / Adjusted Severity mapped from STIG finding + * Scheduled completion date (calculated based on severity) + +2. Asset Management: + + * The Assets tab displays a live feed of affected assets from STIG Manager + * Assets are automatically updated based on the current state in STIG Manager + * Assets cannot be manually added/removed as they are managed by STIG Manager + +Tenable Integration +^^^^^^^^^^^^^^^^^^ +When creating a POAM from Tenable findings: + +1. C-PAT automatically populates: + + * Description + * Vulnerability Source (set to "ACAS") + * Plugin ID + * Raw Severity / Adjusted Severity (mapped from Tenable severity) + * IAVM information (when applicable) + * Scheduled completion date (calculated based on severity) + +2. Asset Management: + + * The Assets tab shows real-time affected assets from Tenable + * Asset list updates automatically based on current Tenable data + * Assets cannot be manually modified as they reflect live Tenable data + + +Field Definitions +^^^^^^^^^^^^^^^^^ + +POAM Status + * Draft - Initial state + * Submitted + * Pending CAT-I Approval + * Extension Requested + * Approved + * Rejected + * Closed + * False-Positive + * Expired + +Description + * Control Vulnerability Description: Describes the vulnerability identified during assessment. This is pulled directly from the assessment procedure entry or technical assessment method (e.g., STIG test case) where applicable. Otherwise it must be manually entered in the NC status for the vulnerability. + +Source Identifying Control Vulnerability + * Identifies the source of the vulnerability (e.g., program review, test and evaluation program findings, IG DoD audit, and GAO audit). + +Vulnerability ID + * Security Checks - NIST -53Rev 4 Assessment Procedure, STIG / SRG Vulnerability ID, or ACAS Plugin ID (Do not leave this field blank). + +Raw Severity + * The initial or starting severity of the vulnerability prior to implementing mitigations and/or compensating Controls. + +Adjusted Severity + * Resulting Residual Risk after Proposed Mitigations: The risk level expected after any proposed mitigations are implemented. Proposed mitigations should be appropriately documented as POA&M milestones + +Impact Description + * Describe the identified impact. + +Predisposing Conditions + * A condition existing within an organization, a mission or business process, enterprise architecture, information system, or environment of operation, which affects (i.e., increases or decreases) the likelihood that threat events, once initiated, result in adverse impacts. + +Scheduled Completion Date + * Target completion date for resolving the vulnerability. This target completion date can stretch beyond the potential 3-year authorization window and must accurately reflect the resolution timetable. Please note that the initial date entered may not be changed. When a vulnerability severity value is resolved, the agency should note the actual completion date. + +.. note:: + POAM Scheduled Completion Date is automated based on the severity of the vulnerability. CAT I - Critical and CAT I - High: 30 days, CAT II - Medium: 180 days, CAT III - Low and CAT III - Informational: 365 days. + +Required Resources + * Estimated funding or manpower resources required to resolve the security vulnerability (i.e., full-time equivalent). + +Milestones + * A milestone identifies specific requirements for correcting an identified vulnerability. The initial milestones and completion dates may not be altered. Any changes to the milestones should be noted in the Milestone Changes within the POAM extension panel. + +Residual Risk + * Residual Risk is automatically determined by the Adjusted Severity Value. If the Adjusted Severity Value is not present, the Residual Risk is determined by the Raw Severity. + +.. note:: + Residual Risk is calculated based on the Adjusted Severity Value. If the Adjusted Severity Value is not present, the Residual Risk is determined by the Raw Severity. + +Likelihood + * Likelihood is automatically determined by the Adjusted Severity Value. If the Adjusted Severity Value is not present, the Likelihood is determined by the Raw Severity. + +.. note:: + Likelihood is calculated based on the Adjusted Severity Value. If the Adjusted Severity Value is not present, the Likelihood is determined by the Raw Severity. + +Mitigations + * Any currently implemented mitigations and/or compensating Controls that will reduce the risk. A planned mitigation or compensating Control cannot lower risk until implemented. \ No newline at end of file diff --git a/docs/source/user/poamexporting.rst b/docs/source/user/poamexporting.rst new file mode 100644 index 00000000..93f7c09e --- /dev/null +++ b/docs/source/user/poamexporting.rst @@ -0,0 +1,186 @@ +POAM Exporting +-------------- + +C-PAT contains the ability to export into the standard eMASS excel format. Listed below are the applicable field mappings for STIG and ACAS originated POAMs. +.. note:: + Draft POAMs are not exported. + +Field Mappings +^^^^^^^^^^^^^^^ + +.. list-table:: POAM Field Mappings + :widths: 10 20 70 + :header-rows: 1 + + * - Column + - eMASS Column Title + - C-PAT Mapped Field + * - C + - Control Vulnerability Description + - Description + * - D + - Controls / APs + - Controls / APs (Handeled behind the scenes) + * - E + - Office/Org + - Exporting user's Office/Org, Full Name, Email. + * - F + - Security Checks + - Source Identifying Control Vulnerability - ID # + * - G + - Resources Required + - Required Resources + * - H + - Scheduled Completion Date + - Scheduled Completion Date + * - I + - Milestone ID + - "1" (Handeled behind the scenes) + * - J + - Milestone with Completion Dates + - Formatted milestone data (See below for milestone formatting details) + * - K + - Milestone Changes + - Formatted milestone change data (See below for milestone formatting details) + * - L + - Source Identifying Vulnerability + - Special formatting rules (See below for Special formatting rules) + * - M + - Status + - Special formatting rules (See below for Special formatting rules) + * - N + - Comments + - Special formatting rules (See below for Special formatting rules) + * - O + - Raw Severity + - Raw Severity (See below for mapping) + * - P + - Devices Affected + - Affected assets list + * - Q + - Mitigations (in-house and in conjunction with the Navy CSSP) + - Mitigations + * - R + - Predisposing Conditions + - Predisposing Conditions + * - S + - Severity + - Raw Severity (See below for mapping) + * - T + - Relevance of Threat + - Default value, see below. + * - U + - Threat Description + - Default value, see below. + * - V + - Likelihood + - Likelihood + * - W + - Impact + - Default value, see below. + * - X + - Impact Description + - Impact Description + * - Y + - Residual Risk Level + - Residual Risk + * - Z + - Recommendations + - Default value, see below. + * - AA + - Resulting Residual Risk after Proposed Mitigations + - Adjusted Severity (See below for mapping) + +Default Values +^^^^^^^^^^^^^^^ + +The following default values are always applied: + +.. code-block:: none + + Column T (Relevance of Threat): "High" + Column U (Threat Description): "ADVERSARIAL - HIGH: Per table D-2 Taxonomy of Threat Sources lists ADVERSARIAL as individual (outsider, insider, trusted insider, privileged insider), therefore the Relevance of Threat defaults to HIGH." + Column W (Impact): "High" + Column Z (Recommendations): "After reviewing documentation, and interviewing system stakeholders, it has been determined that this vulnerability should be mitigated. The ISSO will continue to monitor this vulnerability, and update the POAM as necessary. See mitigations field for detailed mitigation information." + +When no CCI is provided, the following defaults are applied: + +.. code-block:: none + + Column D (Controls / APs): "CM-6.5" + Column N (Comments): "CCI-000366 Control mapping is unavailable for this vulnerability so it is being mapped to CM-6.5 CCI-000366 by default." + +.. note:: + The default CCI logic for exports is seperate from the CCI logic used throughout C-PAT. i.e. In STIG Manager, a query is made to ``/collections/{collectionId}/findings?aggregator=groupId&acceptedOnly=false&benchmarkId={benchmarkId}&projection=assets&projection=ccis`` and the CCI and AP Acronyms are pulled from the CCI projection. For Tenable, a query is made to ``plugin/{pluginId}``; if the plugin has a Patch Publication Date, the CCI is mapped to SI-2.9 / CCI-002605. If the plugin does not have a Patch Publication Date, the CCI is mapped to CM-6.5 / CCI-000366. + Only in the event that the CCI is not found, the default Controls / APs and Comments are applied. + +Severity Mapping +^^^^^^^^^^^^^^^^ + +.. list-table:: Severity Value Mappings + :header-rows: 1 + :widths: 50 50 + + * - Input Severity + - Mapped Value + * - CAT III - Info + - Very Low + * - CAT III - Low + - Low + * - CAT II - Medium + - Moderate + * - CAT I - High + - High + * - CAT I - Critical + - Very High + +Milestone Formatting +^^^^^^^^^^^^^^^^^^^^ +Milestones are formatted in two distinct sections: + +Comments (Column J) +~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + Milestone {Milestone #} + {Milestone Comments} + Milestone Status: {Milestone Status} + Milestone Date: {Milestone Due Date (MM/dd/yyyy)} + +Changes (Column K) +~~~~~~~~~~~~~~~~ + +.. code-block:: none + + Milestone {Milestone #} Changes: + {Milestone Change Comments} + Milestone Status: {Milestone Status} + Milestone Date Change: {Milestone Due Date (MM/dd/yyyy)} + +.. note:: + + Column I contains "1" if comments exist, otherwise the column remains empty. + +Special Handling +^^^^^^^^^^^^^^^^ + +Vulnerability Source (Column L) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **STIG**: Formatted as {STIG TITLE} :: {Revision} Benchmark Date: {Last Revision Date} +* **ACAS**: Plugin Name + +Status Mapping (Column M) +~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **Closed**: Mapped to "Completed" +* **Others**: Mapped to "Ongoing" + +Comments Mapping (Column N) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, comments are mapped to contain the following format: + +.. code-block:: none + + CCI-{CCI #} + (AS APPLICABLE) "Control mapping is unavailable for this vulnerability so it is being mapped to CM-6.5 CCI-000366 by default." + "Local Site Impact: {Local Site Impact}" \ No newline at end of file diff --git a/docs/source/user/stigman.rst b/docs/source/user/stigman.rst new file mode 100644 index 00000000..d02cd04e --- /dev/null +++ b/docs/source/user/stigman.rst @@ -0,0 +1,32 @@ +.. _stigman: +STIG Manager +------------ + +The STIG Manager component was designed to quickly identify vulnerabilities and automate the POAM process. The STIG Manager component contains the main Findings Grid and an additional Findings Chart to quickly visualize the open findings and filter by POAM existience or POAM status. + +Findings Grid +^^^^^^^^^^^^^^^ + +The STIG Manager findings grid is a display of the results from STIG Manager ``api/collections/{collectionId}/findings`` aggregator: ``groupId`` acceptedOnly: ``false`` projection(s): ``stigs, rules``. The results of this API call are then parsed into columns for Group ID, Rule Title, Benchmark ID, Severity, and [affected] Asset Count. +The results are simultaneously compared against existing POAM's in CPAT to determine the existience of a POAM and the POAM Status, if applicable. The results of this determination are displayed in the first column, labeled POAM. + +The POAM column is color coded to reflect the POAM status. The color coding is as follows: +- Red (X): No POAM exists for this finding. +- Red (Circled Checkmark): POAM exists and is in a status of "Expired", "Rejected", or "Draft". +- Yellow: POAM exists and is in a status of "Submitted", "Pending CAT-I Approval", or "Extension Requested". +- Green: POAM exists and is in a status of "Approved" +- Grey: The vulnerability is listed as being "Associated" with an existing POAM. This result is often the case when one master POAM is sufficient to cover multiple similar findings. +- Black: POAM exists and is in a status of "Closed" or "False-Positive". + +.. note:: + The buttons in the POAM column are clickable and will also display a tooltip with additional details when hovered over. + +In cases where a POAM exists, clicking the aforementioned icon will direct the user to the POAM details page for further information. + +In cases where a POAM does not exist, clicking the aforementioned icon will submit an additional query to STIG Manager ``api/stigs/rules/{ruleId}`` projection(s): ``detail, check, fix`` and a query to ``api/stigs/`` while the user is being directed to the POAM creation page. +Upon arrival, the user will be presented with a POAM draft that contains a toggleable section that contains STIG Manager Rule, Check, and Fix data. The POAM Description, Source Identifying Control Vulnerability, STIG Title, Source Identifying Control Vulnerability - ID #, Raw Severity value, Adjusted Severity Value, Scheduled Completion Date, Submitted Date, Residual Risk, Liklihood, and Assets automated based upon the data from STIG Manager. + +By default, the Scheduled Completion Date will be set to 30 days for CAT I (High), 180 days for CAT II (Medium), and 365 days for CAT III (Low) vulnerabilities. The Scheduled Completion Date can be manually adjusted by the user as needed to align with organizational policy. + +.. note:: + If appropriately configured in the Administrative Portal, the A&A Package and Approver fields will also be auto-populated with the appropriate data. \ No newline at end of file diff --git a/docs/source/user/tenable.rst b/docs/source/user/tenable.rst new file mode 100644 index 00000000..5ebabd8a --- /dev/null +++ b/docs/source/user/tenable.rst @@ -0,0 +1,197 @@ +.. _tenable: + +Tenable +------- + +The Tenable component is a comprehensive compilation of tools that provides a large majority of functionality contained in Tenable.sc in addition to numerous expanded capabilities. The tenable component is comprised of the Main Vulnerabilities, IAV Vulnerabilities, and Solutions components. + +Main Vulnerabilities Component +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Main Vulnerabilities Component will display a table originating from Tenable's Vulnerabilities Summary (API tool ``sumid``) with filters to exclude "Informational" severity and include only items where the vulnerability was observed within the last 30 days by default. + +Default Display +""""""""""""" +When the Vulnerability Summary view is selected, the component will display columns for the following fields: +``POAM`` ``Plugin ID`` ``Name`` ``Family`` ``Severity`` ``VPR`` ``IAV`` ``Navy Comply Date`` ``Total`` ``Host Total`` + +Predefined Filters +"""""""""""""""" +To access the filter menu, a filter button is available to the top left of the table. At the top of the filter panel, a dropdown has been provided with several pre-made filters: + +.. list-table:: Tenable Predefined Filters + :widths: 30 70 + :header-rows: 1 + + * - Filter Preset + - Applied Filters + * - Vulnerability Published 30+ Days + - | vulnerabilityPublished = 30:all + * - Exploitable Findings 7+ Days + - | exploitAvailable = true + | vulnerabilityPublished = 7:all + * - Exploitable Findings 30+ Days + - | exploitAvailable = true + | vulnerabilityPublished = 30:all + * - Critical/High 7+ Days + - | severity = [3, 4] + | vulnerabilityLastObserved = 0:30 + | vulnerabilityPublished = 7:all + * - Critical/High 14+ Days + - | severity = [3, 4] + | vulnerabilityLastObserved = 0:30 + | vulnerabilityPublished = 14:all + * - Critical/High 30+ Days + - | severity = [3, 4] + | vulnerabilityLastObserved = 0:30 + | vulnerabilityPublished = 30:all + * - Medium 180+ Days + - | severity = [2] + | vulnerabilityLastObserved = 0:30 + | vulnerabilityPublished = 180:all + * - Low 365+ Days + - | severity = [1] + | vulnerabilityLastObserved = 0:30 + | vulnerabilityPublished = 365:all + * - Cisco Findings 30+ Days + - | pluginFamily = [33] + | vulnerabilityLastObserved = 0:30 + | severity = [1, 2, 3, 4] + * - Database Findings 30+ Days + - | pluginFamily = [31] + | vulnerabilityLastObserved = 0:30 + | severity = [1, 2, 3, 4] + * - F5 Findings 30+ Days + - | pluginFamily = [57] + | vulnerabilityLastObserved = 0:30 + | severity = [1, 2, 3, 4] + * - Linux/Ubuntu Findings 30+ Days + - | pluginFamily = [1, 14] + | vulnerabilityLastObserved = 0:30 + | severity = [1, 2, 3, 4] + +Additional Filters +"""""""""""""""" +Additional filters are available for the following items inside of the main filter panel: +``ACR`` ``AES`` ``AES Severity`` ``Accept Risk`` ``Address`` ``Agent ID`` ``Application CPE`` ``Assets`` ``Audit File`` ``CCE ID`` ``Cross References`` ``CVE ID`` ``CVSS v2 Score`` ``CVSS v2 Vector`` ``CVSS v3 Score`` ``CVSS v3 Vector`` ``Data Format`` ``DNS Name`` ``Exploit Available`` ``Exploit Frameworks`` ``Host ID`` ``IAVM ID`` ``MS Bulletin ID`` ``Mitigated`` ``NetBIOS Name`` ``Patch Published`` ``Plugin Family`` ``Plugin ID`` ``Plugin Modified`` ``Plugin Name`` ``Plugin Published`` ``Plugin Type`` ``Port`` ``Protocol`` ``Recast Risk`` ``STIG Severity`` ``Scan Policy Plugins`` ``Severity`` ``Users`` ``Vulnerability Discovered`` ``Vulnerability Last Observed`` ``Vulnerability Priority Rating`` ``Vulnerability Published`` ``Vulnerability Text`` ``Vulnerability Type`` + +Column filters are available for the following items when the Vulnerability Summary view is selected: +``POAM`` ``IAV`` ``Navy Comply Date`` + +.. note:: + Because of the potential for large amounts of data to be returned, Tenable server side pagination and server side filtering are used to limit the amount of data returned to the client when Vulnerability List view is selected in the main vulnerabilities component. Local filtering for POAM, IAV, and Navy Comply Date are only available when the Vulnerability Summary view is selected. All externally processed filters (filter panel items) are available in both views. + +View Navigation +""""""""""""" +To navigate between Vulnerability Summary (API Tool ``sumid``) and Vulnerability List (API Tool ``listvuln``) a user has two options: +1. A button has been provided adjacent to the filtering buttons and can be identified by the magnifying glass icon that will change the vulnerability view +2. Clicking the row of a particular vulnerability will apply a filter for the selected plugin ID and change to Vulnerability List view + +View Specific Columns +""""""""""""""""""" +Vulnerability List View adds the following additional columns: +``IP Address`` ``ACR`` ``AES`` ``NewBIOS`` ``DNS`` ``MAC Address`` ``Port`` ``Protocol`` ``Agent ID`` ``Host ID`` + +Vulnerability Summary View adds the following additional columns: +``Total`` ``Host Total`` + +IAV Vulnerabilities Component +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The IAV Vulnerabilities Component displays a table originated from Tenable's vulnerability summary with filters to only return Plugin ID's that are mapped to an IAV #, exclude "Informational" severity, and exclude items that have been superseded by other vulnerabilities. + +Default Display +""""""""""""" +When the IAV vulnerability table is initially displayed, the component will show columns for the following fields by default: +``POAM`` ``Plugin ID`` ``Name`` ``Family`` ``Severity`` ``VPR`` ``IAV`` ``Navy Comply Date`` ``Superseded By`` ``Total`` ``Host Total`` + +.. note:: + While similar to the main vulnerabilities view, the IAV Vulnerabilities Component loads the entire dataset and enables local column filtering rather than Tenable sever side filtering. This change allows for ``POAM`` ``IAV`` ``Navy Comply Date`` filtering in either the Vulnerability List view or the Vulnerability Summary view. + +Toolbar Controls +"""""""""""""" +To access the filter menu, several controls are available in the toolbar: +1. A global search input field for filtering across all columns +2. A filter button that provides access to a Navy Comply Date dropdown with the following pre-made filters: + + * All Overdue + * 90+ Days Overdue + * 30-90 Days Overdue + * 0-30 Days Overdue + * 0-14 Days Overdue + * 0-7 Days Overdue + * Due Within 7 Days + * Due Within 14 Days + * Due Within 30 Days + * Due Within 90 Days + +3. A clear filter button to reset to default filters +4. A view toggle button to switch between Summary and List views +5. A column selector to customize visible columns + +View Options +""""""""""" +The component provides two primary views: + +Summary View +''''''''''' +Includes ``Total`` and ``Host Total`` columns. + +List View +''''''''' +Expands to show additional columns: +``IP Address`` ``ACR`` ``AES`` ``NetBIOS`` ``DNS`` ``MAC Address`` ``Port`` ``Protocol`` ``Agent ID`` ``Host ID`` + +Solutions Component +^^^^^^^^^^^^^^^^^ + +The Solutions Component provides a table view of solutions from Tenable, sorted by risk reduction percentage. The component automatically applies a filter for the repository that the user is currently viewing. + +Default Display +""""""""""""" +The solutions table displays the following columns by default: + +``Solution`` ``Risk Reduction`` ``Hosts Affected`` ``Vulnerabilities`` ``VPR`` ``CVSS v3 Base Score`` + +Toolbar Controls +"""""""""""""" +The toolbar provides several controls: + +1. A global search input field for filtering across all columns +2. A clear filter button to reset all filters +3. An export button for downloading the data as CSV + +Filtering Capabilities +"""""""""""""""""""" +Each column supports individual filtering. Available filter types include: + +* Text filtering for ``Solution`` +* Numeric filtering for: + - ``Risk Reduction`` (percentage) + - ``Hosts Affected`` (count) + - ``Vulnerabilities`` (count) + - ``VPR`` (score) + - ``CVSS v3 Base Score`` (score) + +Solution Details Dialog +""""""""""""""""""""" +Clicking a solution row opens a detailed view with three main sections: + +1. Solution Summary Statistics + - Hosts Affected count + - Total Vulnerabilities + - VPR Score + - CVSS v3 Base Score + +2. Vulnerabilities Table + Shows all vulnerabilities addressed by the solution with columns: + ``Plugin ID`` ``VPR`` ``CVSS V3`` ``Host Total`` + +3. Affected Hosts Table + Lists all hosts requiring the solution with columns: + ``IP Address`` ``NetBIOS`` ``DNS`` ``OS CPE`` ``Repository`` + +The dialog provides separate search and filtering capabilities for both the vulnerabilities and affected hosts tables. + +.. note:: + All data is automatically filtered based on the user's current repository. The solutions are sorted by default using the Risk Reduction percentage in descending order to highlight the most impactful remediation actions. \ No newline at end of file