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_API_KEY=<API key>
EMASSER_API_KEY_USER_UID=<unique identifier for the API Key (EMASSER_API_KEY_API_KEY)
EMASSER_HOST=<FQDN of the eMASS server>
EMASSER_KEY_FILE_PATH=<path to your eMASS key in PEM format>
EMASSER_CERT_FILE_PATH=<path to your eMASS certificate in PEM format>
EMASSER_KEY_PASSWORD=<password for the key given in EMASSER_KEY_FILE_PATH>

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_POCH_TO_DATETIME=<convert epoch to data/time value - true or false (default false)>

* 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).

API Endpoints Provided

GET

/api
/api/system
/api/systems
/api/systems/{systemId}
/api/system-roles
/api/system-roles/{roleCategory}
/api/systems/{systemId}/controls
/api/systems/{systemId}/test-results
/api/systems/{systemId}/poams
/api/systems/{systemId}/poams/{poamId}
/api/systems/{systemId}/poams/{poamId}/milestones
/api/systems/{systemId}/poams/{poamId}/milestones/{milestoneId})
/api/systems/{systemId}/artifacts
/api/systems/{systemId}/artifacts-export
/api/systems/{systemId}/approval/cac
/api/systems/{systemId}/approval/pac
/api/cmmc-assessments
/api/workflow-definitions
/api/systems/{systemId}/workflow-instances

POST

/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}/static-code-scans
/api/systems/{systemId}/cloud-resource-results
/api/systems/{systemId}/container-scan-results

PUT

/api/systems/{systemId}/controls
/api/systems/{systemId}/poams
/api/systems/{systemId}/poams/{poamId}/milestones
/api/systems/{systemId}/artifacts

DELETE

/api/systems/{systemId}/poams
/api/systems/{systemId}/poams/{poamId}/milestones
/api/systems/{systemId}/artifacts

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...
  emasser get cmmc                  # Get CMMC assessment information
  emasser get controls              # Get system Controls
  emasser get help [COMMAND]        # Describe subcommands or one specific su...
  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 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 --filename=FILENAME --systemId=N  # Get artifa...
  emasser get artifacts forSystem --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 --filename=FILENAME --systemId=N

Options:
  --systemId=N                   # A numeric value representing the system identification
  --filename=FILENAME            # The artifact file name
  [--compress], [--no-compress]  # BOOLEAN - true or false.

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
--includePackage	BOOLEAN - true or false
--policy	Possible values: diacap, rmf, reporting

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

parameter	type or values
--roleCategory	Possible values: PAC, CAC, Other
--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
--controlAcronyms	String - The system acronym(s) e.g "AC-1, AC-2"
--ccis	String - The system CCIS string numerical value
--latestOnly	BOOLEAN - true or false

parameter	type or values
--scheduledCompletionDateStart	Date - Unix time format (e.g. 1499644800)
--scheduledCompletionDateEnd	Date - Unix time format (e.g. 1499990400)
--controlAcronyms	String - The system acronym(s) e.g "AC-1, AC-2"
--ccis	String - The system CCIS string numerical value
--systemOnly	BOOLEAN - true or false

parameter	type or values
--systemId	Integer - Unique system identifier
--poamId	Integer - Unique poam identifier

parameter	type or values
--filename	The artifact file name
--controlAcronyms	String - The system acronym(s) e.g "AC-1, AC-2"
--ccis	String - The system CCIS string numerical value
--systemOnly	BOOLEAN - true or false

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

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

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 AP 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`
Test results cannot be saved if there is more than one test result per CCI	`cci`

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
--systemId	Integer - Unique system identifier
--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

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
--externalUid	String - External unique identifier for use with associating POA&M Items
--controlAcronym	String - Control acronym associated with the POA&M Item. NIST SP 800-53 Revision 4 defined
--cci	String - CCI associated with the test result
--securityChecks	String - Security Checks that are associated with the POA&M
--rawSeverity	Possible values: I, II, III
--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 - Include description of Security Control’s impact
--residualRiskLevel	Possible values: Very Low, Low, Moderate, High, Very High
--recommendations	String - Include recommendations
--mitigation	String - Include mitigation explanation

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

parameter	type or values
--description	String - Artifact description. 2000 Characters
--refPageNumber	String - Artifact reference page number. 50 Characters
--ccis	String - CCIs associated with artifact
--controls	String - Control acronym associated with the artifact. NIST SP 800-53 Revision 4 defined
--artifactExpirationDate	Date - Date Artifact expires and requires review. In Unix Date Format
--lastReviewedDate	Date - Date Artifact was last reviewed. In Unix Date Format

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

parameter	type or values
--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

parameter	type or values
--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

parameter	type or values
--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

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

Files

features.md

Latest commit

History

features.md

File metadata and controls

emasser CLI Features

Environment Variables

Configuring the .env File

Required and Optional Environment Variables

Common emasser Endpoint Requests Information

Invoking emasser CLI Commands

API Endpoints Provided

GET

POST

PUT

DELETE

Endpoints CLI help

Usage - GET

get test connection

get system

get system id

get system byId

get systems

get roles

get controls

get test_results

get poams

get milestones

get artifacts

get cac

get pac

get cmmc

get workflow_definitions

get workflow_instances

Usage - POST

post test_results

post poams

post milestones

post artifacts

post cac

post pac

post static_code_scan

post cloud_resource

post container

Usage - PUT

put controls

put poams

put milestones

put artifacts

Usage - DELETE

delete poams

delete milestones

delete artifacts

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 cmmc`

`get workflow_definitions`

`get workflow_instances`

`post test_results`

`post poams`

`post milestones`

`post artifacts`

`post cac`

`post pac`

`post static_code_scan`

`post cloud_resource`

`post container`

`put controls`

`put poams`

`put milestones`

`put artifacts`

`delete poams`

`delete milestones`

`delete artifacts`

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
--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

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

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
--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