eMASSer CLI Features

Environment Variables

To facilitate setting the required environment variables the eMASSer CLI utilized the zero-dependency module to load these variables from a .env file.

Configuring the `.env` File

An .env-example file is provided with the required and optional fields.

Modify the .env_example as necessary and save it as a .env file.

Place the file on the path where the eMASSer command is executed.

Required and Optional Environment Variables

The following environment variables are required:

EMASSER_API_KEY=<The eMASS API key (api-key)>
EMASSER_HOST_URL=<The Full Qualified Domain Name (FQDN) for the eMASS server>
EMASSER_KEY_FILE_PATH=<The eMASS key.pem private key file in PEM format (.pem)>
EMASSER_CERT_FILE_PATH=<The eMASS client.pem certificate file in PEM format (.pem)>
EMASSER_KEY_FILE_PASSWORD=<Secret phrase used to protect the encryption key>

Certain eMASS integrations may not require (the majority do) this variable:

EMASSER_USER_UID=<The eMASS User Unique Identifier (user-uid)>

The following environment variables are optional*:

EMASSER_CLIENT_SIDE_VALIDATION=<Client side validation - true or false (default true)>
EMASSER_VERIFY_SSL=<Verify SSL - true or false (default true)>
EMASSER_VERIFY_SSL_HOST=<Verify host SSL - true or false (default true)>
EMASSER_DEBUGGING=<Set debugging - true or false (default false)>
EMASSER_CLI_DISPLAY_NULL=<Display null value fields - true or false (default true)>
EMASSER_EPOCH_TO_DATETIME=<Convert epoch to data/time value - true or false (default false)>
EMASSER_DOWNLOAD_DIR=<Directory where exported files are saved (default eMASSerDownloads)>?

* If not provided defaults are used

The proper format to set these variables in the .env files is as follows:

export [VARIABLE_NAME]='value'

NOTE eMASSer requires authentication to an eMASS instance as well as authorization to use the eMASS API. This authentication and authorization is not a function of eMASSer and needs to be accomplished with the eMASS instances owner organization. Further information about eMASS credential requirements refer to Defense Counterintelligence and Security Agency about eMASS access.

Common eMASSer Endpoint Requests Information

To invoke any boolean parameters use –parameterName for TRUE and –no-parameterName for FALSE
The eMASS API provides the capability of updating multiple entries within several endpoints, however the eMASSer CLI, in some cases only supports updating one entry at the time.

Invoking eMASSer CLI Commands

The CLI invoke commands listed in this document shows them when executing from the source code (after a pull from GitHub). Please reference the eMASSer README on how to invoke the CLI using other available executables (gem or docker).

GET Endpoints

Dashboards

POST Endpoints

/api/api-key
/api/systems/{systemId}/test-results
/api/systems/{systemId}/poam
/api/systems/{systemId}/poam/{poamId}/milestones
/api/systems/{systemId}/artifacts
/api/systems/{systemId}/approval/cac
/api/systems/{systemId}/approval/pac
/api/systems/{systemId}/hw-baseline
/api/systems/{systemId}/sw-baseline
/api/systems/{systemId}/device-scan-results
/api/systems/{systemId}/cloud-resource-results
/api/systems/{systemId}/container-scan-results
/api/systems/{systemId}/static-code-scans

PUT Endpoints

/api/systems/{systemId}/controls
/api/systems/{systemId}/poams
/api/systems/{systemId}/poams/{poamId}/milestones
/api/systems/{systemId}/artifacts
/api/systems/{systemId}/hw-baseline
/api/systems/{systemId}/sw-baseline

DELETE Endpoints

/api/systems/{systemId}/poams
/api/systems/{systemId}/poams/{poamId}/milestones
/api/systems/{systemId}/artifacts
/api/systems/{systemId}/hw-baseline
/api/systems/{systemId}/sw-baseline
/api/systems/{systemId}/cloud-resource-results
/api/systems/{systemId}/container-scan-results

Endpoints CLI help

Each CLI endpoint command has several layers of help.

Using help after a get, put, post, or delete command lists all available endpoint calls. The following command would list all available GET endpoints commands.

  $ bundle exec exe/emasser get help
  Commands:
    emasser get artifacts             # Get system Artifacts
    emasser get cac                   # Get location of one or many controls in CAC
    emasser get cmmc                  # Get CMMC assessment information
    emasser get controls              # Get system Controls
    emasser get dashboards            # Get dashboard information
    emasser get hardware              # Get one or many hardware assets in a system
    emasser get milestones            # Get system Milestones
    emasser get pac                   # Get status of active workflows in a system
    emasser get poams                 # Get system Poams
    emasser get roles                 # Get all system roles or by category Id
    emasser get software              # Get one or many software assets in a system
    emasser get system                # Get a system ID given name/owner, or ge...
    emasser get systems               # Get all systems
    emasser get test                  # Test connection to the configured eMASS...
    emasser get test_results          # Get system Test Results
    emasser get workflow_definitions  # Get workflow definitions in a site
    emasser get workflow_instances    # Get workflow instance by system and/or ...

Preceding any command with help provides help for the command. The following command would list all available sub-commands and options for the get artifacts endpoint command.

  $ bundle exec exe/emasser get help artifacts
  commands:
    emasser get artifacts export -f, --filename=FILENAME -s, --systemId=N  # Get artifa...
    emasser get artifacts forSystem -s, --systemId=N                       # Get all sy...
    emasser get artifacts help [COMMAND]                                   # Describe s...

Using help after any command lists all available options. The following command would list all available options for the get artifacts export endpoint command.

  $ bundle exec exe/emasser get artifacts help export
  Usage:
    emasser get artifacts export -f, --filename=FILENAME -s, --systemId=N

  Options:
    -s, --systemId=N                     # A numeric value representing the system identification
    -f, --filename=FILENAME              # The artifact file name
    -C, |compress], |no-compress]    # BOOLEAN - true or false.
    -o, |printToStdout=PRINTTOSTDOUT]  # Output file content to terminal - not valid for zip files      

The same format is applicable for POST, PUT and DELETE requests as well, however there may be additional help content

Usage - GET

`get test connection`

The Test Connection endpoint provides the ability to verify connection to the web service.

$ bundle exec exe/emasser get test connection

A return of success from the call indicates that the CLI can reach the configure server URL. References Required Environment Variables for the necessary environment variables.

parameter	type or values
-I, –includePackage	BOOLEAN - true or false
-p, –policy	Possible values: diacap, rmf, reporting

parameter	type or values
-c, –coamsId	Cyber Operational Attributes Management System (COAMS) string Id
-t, –ditprId	DoD Information Technology (IT) Portfolio Repository (DITPR) string id
-r, –registrationType	Possible values: assessAndAuthorize, assessOnly, guest, regular, functional,
	cloudServiceProvider, commonControlProvider
-I, –includeDecommissioned	BOOLEAN - true or false
-M, –includeDitprMetrics	BOOLEAN - true or false
-P, –includePackage	BOOLEAN - true or false
-p, –policy	Possible values: diacap, rmf, reporting
_S, –reportsForScorecard	BOOLEAN - true or false

parameter	type or values
-c, –roleCategory	Possible values: PAC, CAC, Other
-r, –role	Possible values: AO, Auditor, Artifact Manager, C&A Team, IAO, ISSO, PM/IAM, SCA, User Rep (View Only), Validator (IV&V)

parameter	type or values
-a, –controlAcronyms	String - The system acronym(s) e.g “AC-1, AC-2”
-p, –assessmentProcedures	String - The system Security Control Assessment Procedure e.g “AC-1.1,AC-1.2”
-c, –ccis	String - The system CCIS string numerical value
-L, –latestOnly	BOOLEAN - true or false

parameter	type or values
-d, –scheduledCompletionDateStart	Date - Unix time format (e.g. 1499644800)
-e, –scheduledCompletionDateEnd	Date - Unix time format (e.g. 1499990400)
-a, –controlAcronyms	String - The system acronym(s) e.g “AC-1, AC-2”
-p, –assessmentProcedures	String - The system Security Control Assessment Procedure e.g “AC-1.1,AC-1.2”
-c, –ccis	String - The system CCIS string numerical value
-Y, –systemOnly	BOOLEAN - true or false

parameter	type or values
-s, –systemId	Integer - Unique system identifier
-p, –poamId	Integer - Unique poam identifier

parameter	type or values
-f, –filename	The artifact file name
-a, –controlAcronyms	String - The system acronym(s) e.g “AC-1, AC-2”
-p, –assessmentProcedures	String - The system Security Control Assessment Procedure e.g “AC-1.1,AC-1.2”
-c, –ccis	String - The system CCIS string numerical value
-Y, –systemOnly	BOOLEAN - true or false

parameter	type or values
-C, –compress	BOOLEAN - true or false.
-o, –printToStdout	BOOLEAN - true or false - Output file content to terminal - not valid for zip files

parameter	type or values
-i, –pageIndex	Integer - The index of the starting page (default first page 0)
-s, –pageSize	Integer - The number of entries per page (default 20000)

parameter	type or values
-I, –includeInactive	BOOLEAN - true or false
-r, –registrationType	Possible values: assessAndAuthorize, assessOnly, guest, regular, functional,
	cloudServiceProvider, commonControlProvider

Business Rule	Parameter/Field
Tests Results cannot be saved if the “Test Date” is in the future.	`testDate`
Test Results cannot be saved if a Security Control is “Inherited” in the system record.	`description`
Test Results cannot be saved if an Assessment Procedure is “Inherited” in the system record.	`description`
Test Results cannot be saved if the Assessment Procedure does not exist in the system.	`description`
Test Results cannot be saved if the control is marked “Not Applicable” by an Overlay.	`description`
Test Results cannot be saved if the control is required to be assessed as “Applicable” by an Overlay.	`description`
Test Results cannot be saved if the Tests Results entered is greater than 4000 characters.	`description`
Test Results cannot be saved if the following fields are missing data:	`complianceStatus`, `testDate`, `testedBy`, `description`

status	Required Fields
Risk Accepted	comments
Ongoing	scheduledCompletionDate, milestones (at least 1)
Completed	scheduledCompletionDate, comments, completionDate, milestones (at least 1)
Not Applicable	POAM can not be created

parameter	type or values
-s, –systemId	Integer - Unique system identifier
–status	Possible Values: Ongoing,Risk Accepted,Completed,Not Applicable
–vulnerabilityDescription	String - Vulnerability description for the POA&M Item
–sourceIdentifyingVulnerability	String - Include Source Identifying Vulnerability text
–pocOrganization	String - Organization/Office represented
–resources	String - List of resources used. Character Limit = 250

parameter	type or values
–milestones	JSON - see milestone format
–pocFirstName	String - First name of POC
–pocLastName	String - Last name of POC
–pocEmail**	String - Email address of POC
–pocPhoneNumber	String - Phone number of POC (area code) -* format
–severity	Possible values - Very Low, Low, Moderate, High, Very High
–scheduledCompletionDate	Date - Required for ongoing and completed POA&M items. Unix time format
–completionDate	Date - Field is required for completed POA&M items. Unix time format
–comments	String - Field is required for completed and risk accepted POA&M items.

parameter	type or values
-C, –includeComments	BOOLEAN - true or false
-D, –includeDecommissionSystems	BOOLEAN - true or false.
-p, –pageIndex	Integer - The page number to query
-d, –sinceDate	Date - The Workflow Instance date. Unix date format
-s, –status	Possible values: active, inactive, all

parameter	type or values
-I, –excludeInherited	BOOLEAN - If no value is specified, includes inherited data
-i, –pageIndex	Integer - The index of the starting page (default first page 0)
-s, –pageSize	Integer - The number of entries per page (default 20000)

parameter	type or values
-s, –systemId	Integer - Unique system identifier
–assessmentProcedure	String - The Security Control Assessment Procedure being assessed
–testedBy	String - Last Name, First Name. 100 Characters.
–testDate	Date - Unix time format (e.g. 1499990400)
–description	String - Include description of test result. 4000 Characters
–complianceStatus	Possible values: Compliant, Non-Compliant, Not Applicable

parameter	type or values
-s, –systemId	Integer - Unique system identifier
-T, –isTemplate	Boolean - Indicates whether an artifact is a template
-t, –type	Possible Values: Procedure, Diagram, Policy, Labor, Document, Image, Other, Scan Result, Auditor Report
-c, –category	Possible Values: Implementation Guidance, Evidence
-f, –files	String - File names (to include path) to be uploaded into eMASS as artifacts

parameter	type or values
-s, –systemId	Integer - Unique system identifier
-a, –controlAcronym	String - Control acronym associated with the POA&M Item. NIST SP 800-53 Revision 4 defined

parameter	type or values
-s, –systemId	Integer - Unique system identifier
-f, –workflow	Possible Values: Assess and Authorize, Assess Only, Security Plan Approval
-n, –name	String - Package name. 100 Characters
-c, –comments	String - Comments submitted upon initiation of the indicated workflow, 4,000 character

parameter	type or values
-s, –systemId	Integer - Unique system identifier
-a, –assetName	String - Name of the hardware asset

parameter	type or values
-s, –systemId	Integer - A numeric value representing the system identification
-S, –softwareId	String - Unique software identifier
-V, –softwareVendor	String - Vendor of the software asset
-N, –softwareName	String - Name of the software asset
-v, –version	String - Version of the software asset

parameter	type or values
-s, –systemId	Integer - Unique system identifier
–provider	string - Cloud service provider name
–resourceId	String - Unique identifier/resource namespace for policy compliance result
–resourceName	String - Friendly name of Cloud resource
–resourceType	String - Type of Cloud resource
–cspPolicyDefinitionId	String - Unique identifier/compliance namespace for CSP/Resource's policy definition/compliance check
–isCompliant	Boolean - Compliance status of the policy for the identified cloud resource
–policyDefinitionTitle	String - Friendly policy/compliance check title. Recommend short title

parameter	type or values
–initiatedBy	String - Person initiating the process email address
–cspAccountId	String - System/owner's CSP account ID/number
–cspRegion	String - CSP region of system
–isBaseline	Boolean - Flag that indicates in results is a baseline
Tags Object (tags)
–text	String - Text that specifies the tag type
Compliance Results Array Objects (complianceResults)
–assessmentProcedure	String - Comma separated correlation to Assessment Procedure (i.e. CCI number for DoD Control Set)
–complianceCheckTimestamp	Date - The compliance check date - Unix time format
–complianceReason	String - Reason/comments for compliance result
–control	String - Comma separated correlation to Security Control (e.g. exact NIST Control acronym)
–policyDeploymentName	String - Name of policy deployment
–policyDeploymentVersion	String - Version of policy deployment
–severity	Possible Values: Low, Medium, High, Critical

eMASSer CLI Features

Environment Variables

Configuring the .env File

Required and Optional Environment Variables

Common eMASSer Endpoint Requests Information

Invoking eMASSer CLI Commands

GET Endpoints

Test Connection

System

System Roles

Controls

Test Results

POA&Ms

Milestones

Artifacts

CAC

PAC

Hardware Baseline

Software Baseline

CMMC Assessment

Workflow Definition

Workflow Instances

Dashboards

POST Endpoints

PUT Endpoints

DELETE Endpoints

Endpoints CLI help

Usage - GET

get test connection

get system

get system id

get systems

get roles

get controls

get test_results

get poams

get milestones

get artifacts

get cac

get pac

get hardware

get software

get cmmc

get workflow_definitions

get workflow_instances

get dashboards

Usage - POST

post register cert

post test_results

post poams

post milestones

post artifacts

Category

post cac

post pac

post hardware

post software

post device scan results

post cloud_resource

post container

post static_code_scan

Usage - PUT

put controls

put poams

put milestones

put artifacts

put hardware

put software

Usage - DELETE

delete poams

delete milestones

delete artifacts

delete hardware

delete software

delete cloud resource

delete container

Configuring the `.env` File

`get test connection`

`get system`

`get systems`

`get roles`

`get controls`

`get test_results`

`get poams`

`get milestones`

`get artifacts`

`get cac`

`get pac`

`get hardware`

`get software`

`get cmmc`

`get workflow_definitions`

`get workflow_instances`

`get dashboards`

`post register cert`

`post test_results`

`post poams`

`post milestones`

`post artifacts`

`post cac`

`post pac`

`post hardware`

`post software`

`post device scan results`

`post cloud_resource`

`post container`

`post static_code_scan`

`put controls`

`put poams`

`put milestones`

`put artifacts`

`put hardware`

`put software`

`delete poams`

`delete milestones`

`delete artifacts`

`delete hardware`

`delete software`

`delete cloud resource`

`delete container`

parameter	type or values
-s, –systemId	Integer - Unique system identifier
–containerId	String - Unique identifier of the container
–containerName	String - Friendly name of the container
–time	Date - Datetime of scan/result. Unix date format
Bench Marks Object (benchmarks)
–benchmark	String - Identifier of the benchmark/grouping of compliance results
benchmarks.results	Object
–ruleId	String - Identifier for the compliance result, vulnerability, etc.
–status	String - Benchmark result status
–lastSeen	Date - Date last seen, Unix date format

parameter	type or values
–podName	String - Name of pod (e.g. Kubernetes pod)
–podIp	String - IP address of pod
–namespace	String - Namespace of container in container orchestration (e.g. Kubernetes namespace)
Tags Object (tags)
–text	String - Text that specifies the tag type
Bench Marks Object (benchmarks)
–isBaseline	Boolean - True/false flag for providing results as baseline. If true, all existing compliance results for the provided benchmark within the container will be replaced by results in the current call
benchmarks.results	Object
–message	String - Comments for the result

parameter	type or values
-s, –systemId	Integer - Unique system identifier
–applicationName	String - Name of the software application that was assessed
–version	String - The version of the application
–codeCheckName	Strings - Name of the software vulnerability or weakness
–scanDate	Date - The findings scan date - Unix time format
–cweId	String - The Common Weakness Enumerator (CWE) identifier

parameter	type or values
–rawSeverity*	Possible Values: Low, Medium, Moderate, High, Critical
–count	Integer - Number of instances observed for a specified

Value	Required Fields
Planned or Implemented	controlDesignation, estimatedCompletionDate, responsibleEntities, slcmCriticality, slcmFrequency, slcmMethod, slcmMethod, slcmTracking, slcmComments
Not Applicable	naJustification, controlDesignation, responsibleEntities
Manually Inherited	controlDesignation, estimatedCompletionDate, responsibleEntities, slcmCriticality, slcmFrequency, slcmMethod, slcmMethod, slcmTracking, slcmComments

parameter	type or values
–systemId	Integer - Unique system identifier
–acronym	String - The system acronym(s) e.g “AC-1, AC-2”
–responsibleEntities	String - Description of the responsible entities for the Security Control
–controlDesignation	Possible values: Common, System-Specific, or Hybrid
–estimatedCompletionDate	Date - Unix time format (e.g. 1499990400)
–comments	String - Security control comments

parameter	type or values
–commonControlProvider	Possible values: DoD, Component, Enclave
–naJustification	String - Justification for Security Controls deemed Not Applicable to the system
–slcmCriticality	String - Criticality of Security Control regarding SLCM
–slcmFrequency	Possible values - Constantly, Daily, Weekly, Monthly, Quarterly, Semi-Annually, Annually, or Undetermined
–slcmMethod	Possible values: Automated, Semi-Automated, Manual, or Undetermined
–slcmReporting	String - The System-Level Continuous Monitoring reporting
–slcmTracking	String - The System-Level Continuous Monitoring tracking
–slcmComments	String, - Additional comments for Security Control regarding SLCM

parameter	type or values
–implementationStatus	Possible values: Planned, Implemented, Inherited, Not Applicable, or Manually Inherited
–severity	Possible values: Very Low, Low, Moderate, High, Very High
–vulnerabiltySummary	String - The security control vulnerability summary
–recommendations	String - The security control vulnerability recommendation
–relevanceOfThreat	Possible values: Very Low, Low, Moderate, High, Very High
–likelihood	Possible values: Very Low, Low, Moderate, High, Very High
–impact	Possible values: Very Low, Low, Moderate, High, Very High
–impactDescription	String, - Description of the security control impact
–residualRiskLevel	Possible values: Very Low, Low, Moderate, High, Very High
–mitigation	String - Information about the Non-Compliant Security Control’s vulnerabilities
–applicationLayer	String - Navy specific applicablr to Financial Management overlay
–databaseLayer	String - Navy specific applicablr to Financial Management overlay
–operatingSystemLayer	String - Navy specific applicablr to Financial Management overlay

Value	Required Fields
Risk Accepted	comments, resources
Ongoing	scheduledCompletionDate, resources, milestones (at least 1)
Completed	scheduledCompletionDate, comments, resources,
	completionDate, milestones (at least 1)
Not Applicable	POAM can not be created

parameter	type or values
-s, –systemId	Integer - Unique system identifier
–displayPoamId	Integer - Globally unique identifier for individual POA&M Items
–status	Possible Values: Ongoing,Risk Accepted,Completed,Not Applicable
–vulnerabilityDescription	String - Vulnerability description for the POA&M Item
–sourceIdentVuln	String - Include Source Identifying Vulnerability text
–pocOrganization	String - Organization/Office represented
–resources	String - List of resources used. Character Limit = 250