mitre/emass_client

The eMASS client repository maintains the Enterprise Mission Assurance Support Service (eMASS) Representational State Transfer (REST) Application Programming Interface (API) specification and executables.

eMASS Client

The eMASS client repository (emass_client) maintains the Enterprise Mission Assurance Support Service (eMASS) Representational State Transfer (REST) Application Programming Interface (API) specifications and executables. The executables packages currently provided are: RubyGem, TypeScript Node, and Python.

NOTE: A CLI tool called emasser, has been developed that makes use of the emass_client RubyGem. Additionally, the SAF CLI implements the emass_client npm package.

Highlights

eMASS API Specification

The eMASS API is documented in YAML and can be viewed utilizing a multitude of visualization tools. Included is a dependency-free (and nice looking) rendering tool for viewing the API specification. The documentation is automatically generated using a Continuos Integration (CI) action redoc-cli command line tool.

eMASS API Viewer

This repository allows anyone to visualize and interact with the API’s resources without having any of the implementation logic in place, via hosted or local mock servers. Please reference Developers Instruction on how to setup a local mock server

eMASS API Clients Generation Process

The executable packages (APIs) generated are used to access eMASS data and functionality by external third-party developers, business partners, or internal departments.

The following emass_client executable packages are generated by this repository:

• Ruby - The ruby package is hosted and available in the RubyGems.

• Typescript - The typescript package is hosted and available in the NpmRegistry.

• Python - The python package is hosted and available in the PyPIRegistry.

Making Changes to eMASS Clients

Changes to the eMASS clients are made by modifying the eMASS API specification file eMASSRestOpenApi.yaml. Modification to this file triggers the clients' generation actions where all client packages are generated, and published to the appropriate repositories when the PR branch is merged into the main branch.

After either forking or creating a branch for the main repository update the code via a pull request (PR) or directly on the branch.

The proper process for making client code updates are as follows:

• Step 1 Update the eMASS API specification file eMASSRestOpenApi.yaml

• Step 2 Make the necessary changes (update the version field) to the clients generation configuration files:

  • Ruby (src/openapi/templates/ruby/ruby-generator-config.json)
  • Typescript(src/openapi/templates/typescript/typescript-generator-config.json)
  • Python (src/openapi/templates/python/python-generator-config.json)

• Step 3 Push the content to the repository

• Step 4 Once all test pass merge the pull request

Other Programming Languages

For detail information on how-to generating eMASS clients for other programming languages reference Developers Instructions

Repository Architecture

The process provided by this repository is depicted by the architecture diagram below. In a nutshell, it hosts the eMAASS API specification, documentation, interactive visualization tools, and generates clients for the following languages: ruby, typescript, and python.

Client Application

The emass_client executable packages can be included in other projects, or used to generate CLI tools that require access to an eMASS instance as demonstrated by the diagram below.

NOTICE

© 2020 The MITRE Corporation.

Approved for Public Release; Distribution Unlimited. Case Number 18-3678.

NOTICE

MITRE hereby grants express written permission to use, reproduce, distribute, modify, and otherwise leverage this software to the extent permitted by the licensed terms provided in the LICENSE.md file included with this project.

NOTICE

This software was produced for the U. S. Government under Contract Number HHSM-500-2012-00008I, and is subject to Federal Acquisition Regulation Clause 52.227-14, Rights in Data-General.

No other use other than that granted to the U. S. Government, or to those acting on behalf of the U. S. Government under that Clause is authorized without the express written permission of The MITRE Corporation.

For further information, please contact The MITRE Corporation, Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539, [phone].

emass_client's Issues

Updates to emass client

Axios

Check the OpenAPI auto generator for:

• Verify why axios dependencies for the typescript client is set to 0.2.4
• Check why is it using an offset of the axios code.

Client Code Base

• Generate a python client
• Add python client to Python Package Index (registry)

workflows

Change the following on publish-npm-gpr.yml

• change actions/checkout@v1 to actions/checkout@v3
• change the GPR npm publish public mitre-emass_client-.tgz to npm publish --access public mitre-emass_client-.tgz

Change the following on publish-npm-registry.yml

• change actions/checkout@master to actions/checkout@v3
• remove commented GPR steps

Change the following on publish-npm-gpr.yml and publish-npm-registry.yml

• change runs-on: ubuntu-18.04 to runs-on: ubuntu-20.04
• change actions/setup-node@v1 to actions/setup-node@v3

API endpoints Updates

V3.5

• Added fields to Systems endpoint:
  isHVA - Boolean - [Read-Only] Indicates if the system contains High Value Assets. Does not display if value is null.

V3.6 to V3.9

• Added fields to Systems endpoint:

Name	Field
Is Financial Management	isFinancialManagement
Is Reciprocity	isReciprocity
Reciprocity Exemption	reciprocityExemption
Cloud Computing	cloudComputing
Cloud Type	cloudType
Is SaaS	isSaaS
Is PaaS	isPaa
Is IaaS	isIaaS
Other Service Models	otherServiceModels
Need Date	needDate
Overall Risk Score	overallRiskScore
Is HRR	isHRR
ATC Status	atcStatus
ATC Date	atcDate
ATC Termination Date	atcTerminationDate
System Development Lifecycle	systemDevelopmentLifeCycle

• Added fields to CMMC Assessments endpoint:

Name	Field
Highest Level Order Cage Code	highestLevelOrderCageCode
Certification Unique ID	highestLevelOrderCageCode
POAM	poam
Overall Score	overallScore
OSC Assessment Official Last Name	oscAssessmentOfficialLastName
OSC Assessment Official First Name	oscAssessmentOfficialFirstName
OSC Assessment Official Email	oscAssessmentOfficialEmail
OSC Assessment Official Title	oscAssessmentOfficialTitle

Renamed fields in CMMC Assessments endpoint:

• • Unique Entity Identifier (uniqueEntityIdentifier) -> uei
• • CageCodes (cageCode) → cageCodesInScope
• • CertificateID (certificId) → assessmentId

Removed field from CMMC Assessments endpoint:

• • DUNS -> duns

Added these Dashboard endpoints.

• System Artifacts Summary
• System Artifacts Details
• System Sensor Hardware Summary
• System Sensor Hardware Details
• System Ports/Protocols Summary
• System Ports/Protocols Detail
• VA System FISMA Inventory Crypto Summary
• VA System Threat Risks Summary
• VA System Threat Sources Details
• VA System Threat Architecture Details

V3.7

• Added field to Systems endpoint:
  • Instance - instance

• Renamed field in Systems endpoint:
  • Organization Name → owningOrganization

• Removed field from Systems endpoint:
  • System Owner systemOwner

• Added parameter to Dashboards endpoint:
  • Exclude Inherited → excludeInherited

Fix Artifacts Field

• Field lastReviewedDate should be lastReviewDate type Date [Optional] Date artifact was last reviewed.Unix date format.

Fix Systems Field

The field authorizationStatus is set as an enumeration, limiting the data it can hold, however the specification states that:
* Some eMASS instances have custom Authorization Status values not captured in this list.

• Make the field a free text entry

POAMs Required Fields

When adding a POAM with status value of "Ongoing" it looks like the following fields are required:

• "vulnerabilitySeverityValue: The Severity is required.",
• "relevanceOfThreat: The Relevance of Threat is required.",
• "likelihood: The Likelihood is required.",
• "impact: The Impact is required.",
• "residualRiskLevel: The Residual Risk Level is required."
  These fields are now defined in the business logic of the eMASS API 3.9 as:
  *Note: Certain eMASS instances also require the Risk Analysis fields to be populated:
  • Severity
  • Relevance of Threat
  • Likelihood
  • Impact
  • Residual Risk Level
  • Mitigations

The field- "mitigation" is defined in the API ver 3.9 as optional, however when adding a new POAM, the server response states that it is a required field.

Update Register endpoint

Update the register endpoint such that there is not request body required.

eMASS API V3.11-3.13 Clients updates needed

Need to add the NOTICE and LICENCES files (see here)

---

Need to update the clients (emasser and SAF) system-roles endpoint call.

• The field role should NOT be an enum in get system-roles (query parameter)

• Added assessmentProcedures to get test-results, get poams, get artifacts (query parameter)

• Evaluate the get artifacts export endpoint - file is exported to the temp directory - not there

• POA&Ms - new required field identifiedInCFOAuditOrOtherReview (VA only)

[Required] If not specified, this field will be set to false because it does not accept a null value.

• ppsmRegistrationRequired is a string, however the values listed on the examples are true/false. Should this field be a Boolean?

---

SAF CLI

• get controls - flag acronyms should be a string not Boolean
• update the get dashboards EXAMPLES to: saf emasser get dashboards [dashboard name] [-o, --orgId] [options]
• change flag options for scheduledCompletionDateStart, aliases: '-d' scheduledCompletionDateEnd, aliases: '-e'
• in get workflow_definitions change the -i to -I (all Booleans are capitalized)
• add register endpoint to the help file (https://saf-cli.mitre.org/docs/emasser)
• test the post/put poams endpoints
• saf emasser delete poams change the -P to -p
• saf emasser delete milestones change the -M to -m
• saf emasser delete artifacts change -F to -f