Skip to the content.

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:

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

The following environment variables are optional*:

* 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

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

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

Each CLI endpoint command has several layers of help.

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.

top

get system


The get system command is not a sanctioned eMASS endpoint, it makes use of the get systems endpoint with added business logic.

There are two commands provided by the get system:

To invoke the get system id use the following command:

$ bundle exec exe/emasser get system id --system_name "system name" --system_owner "system owner"

If using a platform that has awk installed the following command can be used to return only the system Id:

$ bundle exec exe/emasser get system --system_name "system name" --system_owner "system owner" | awk "{ print $1 }"  ### get system byId Retrieves the system content for provided identification (ID) number. To invoke the endpoint use  the following command:

$ bundle exec exe/emasser get system byId

top

get systems


To retrieve controls use the following command:

top

get roles


There are two get endpoints for system roles:

top

get controls


To retrieve controls use the following command:

$ bundle exec exe/emasser get controls forSystem -s, --systemId=SYSTEMID

top

get test_results


To retrieve test results use the following command:

$ bundle exec exe/emasser get test_results forSystem -s, --systemId=SYSTEMID

top

get poams


There are two get endpoints for system poams:

top

get milestones


There are two get endpoints for system milestones:

top

get artifacts


There are two get endpoints that provides the ability to view existing Artifacts in a system:

top

get cac


To view one or many Control Approval Chain (CAC) in a system specified system ID use the following command:

  $ bundle exec exe/emasser get cac controls -s, --systemId=SYSTEMID

top

get pac


To view one or many Package Approval Chain (PAC) in a system specified system ID use the following command:

  $ bundle exec exe/emasser get pac package -s, --systemId=SYSTEMID

top

get hardware


To view Hardware Baseline assets use the following command:

  $ bundle exec exe/emasser get hardware assets -s, --systemId=SYSTEMID

top

get software


To view Software Baseline assets use the following command:

  $ bundle exec exe/emasser get software assets -s, --systemId=SYSTEMID

top

get cmmc


To view Cybersecurity Maturity Model Certification (CMMC) Assessments use the following command:

$ bundle exec exe/emasser get cmmc assessments -d, --sinceDate=SINCEDATE 

top

get workflow_definitions


To view Workflow Definitions use the following command:

$ bundle exec exe/emasser get workflow_definitions forSite

top

get workflow_instances


There are two get endpoints to view workflow instances:

top

get dashboards


The Dashboards endpoints provide the ability to view data contained in dashboard exports. In the eMASS front end, these dashboard exports are generated as Excel exports.

All endpoint calls utilize the same parameter values, they are:

The following dashboard endpoint commands are available

  emasser get dashboards application_findings_details           # Get system ...
  emasser get dashboards application_findings_summary           # Get system ...
  emasser get dashboards artifacts_details                      # Get systems...
  emasser get dashboards artifacts_summary                      # Get systems...
  emasser get dashboards assessment_procedures_details          # Get systems...
  emasser get dashboards assignments_details                    # Get user sy...
  emasser get dashboards associations_details                   # Get system ...
  emasser get dashboards atc_iatc_details                       # Get systems...
  emasser get dashboards cmmc_compliance_summary                # Get CMMC As...
  emasser get dashboards cmmc_requirement_objectives_details    # Get CMMC As...
  emasser get dashboards cmmc_security_requirements_details     # Get CMMC As...
  emasser get dashboards cmmc_status_summary                    # Get CMMC As...
  emasser get dashboards coastguard_fisma_metrics               # Get coastgu...
  emasser get dashboards connectivity_ccsd_details              # Get systems...
  emasser get dashboards connectivity_ccsd_summary              # Get systems...
  emasser get dashboards control_compliance_summary             # Get systems...
  emasser get dashboards critical_assets_summary                # Get system ...
  emasser get dashboards device_findings_details                # Get system ...
  emasser get dashboards device_findings_summary                # Get system ...
  emasser get dashboards fisma_inventory_crypto_summary         # Get VA syst...
  emasser get dashboards fisma_inventory_summary                # Get VA syst...
  emasser get dashboards fisma_metrics                          # Get FISMA m...
  emasser get dashboards fisma_saop_summary                     # Get VA OMB-...
  emasser get dashboards hardware_details                       # Get system ...
  emasser get dashboards hardware_summary                       # Get system ...
  emasser get dashboards integration_status_summary             # Get system ...
  emasser get dashboards organization_migration_status_summary  # Get organiz...
  emasser get dashboards poam_details                           # Get system ...
  emasser get dashboards poam_summary                           # Get systems...
  emasser get dashboards ports_protocols_details                # Get system ...
  emasser get dashboards ports_protocols_summary                # Get system ...
  emasser get dashboards privacy_summary                        # Get user sy...
  emasser get dashboards questionnaire_details                  # Get systems...
  emasser get dashboards questionnaire_summary                  # Get systems...
  emasser get dashboards security_control_details               # Get systems...
  emasser get dashboards sensor_hardware_details                # Get system ...
  emasser get dashboards sensor_hardware_summary                # Get system ...
  emasser get dashboards sensor_software_counts                 # Get system ...
  emasser get dashboards sensor_software_details                # Get system ...
  emasser get dashboards sensor_software_summary                # Get system ...
  emasser get dashboards software_details                       # Get system ...
  emasser get dashboards software_summary                       # Get system ...
  emasser get dashboards status_details                         # Get systems...
  emasser get dashboards system_migration_status_summary        # Get system ...
  emasser get dashboards terms_conditions_details               # Get systems...
  emasser get dashboards terms_conditions_summary               # Get systems...
  emasser get dashboards threat_architecture_details            # Get VA Syst...
  emasser get dashboards threat_risk_details                    # Get VA Syst...
  emasser get dashboards threat_risk_summary                    # Get VA Syst...
  emasser get dashboards va_a2_summary                          # Get VA syst...
  emasser get dashboards va_aa_summary                          # Get VA syst...
  emasser get dashboards va_icamp_tableau_poam_details          # Get VA ICAM...
  emasser get dashboards va_pl_109_summary                      # Get VA Syst...
  emasser get dashboards vulnerability_summary                  # Get system ...
  emasser get dashboards workflows_history_details              # Get system ...
  emasser get dashboards workflows_history_stage_details        # Get system ...
  emasser get dashboards workflows_history_summary              # Get system ...

top

Usage - POST

post register cert


The Registration endpoint provides the ability to register a certificate & obtain an API-key.

$ bundle exec exe/emasser post register cert

top

post test_results


Test Result add (POST) endpoint API business rules.

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

To add (POST) test results use the following command:

  $ bundle exec exe/emasser post test_results add [-s --systemId] <value> --assessmentProcedure <value> --testedBy <value> --testDate <value? --description <value> --complianceStatus <value>

Note: If no POA&Ms or Assessment Procedure exist for the control (system), you will get this response: “You have entered a Non-Compliant Test Result. You must create a POA&M Item for this Control and/or AP if one does not already exist.”

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post test_results help add

top

post poams


Plan of Action and Milestones (POA&M) add (POST) endpoint API business rules.

The following fields are required based on the contents of the status field

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

If a POC email is supplied, the application will attempt to locate a user already registered within the application and pre-populate any information not explicitly supplied in the request. If no such user is found, these fields are required within the request.

Business logic, the following rules apply when adding POA&Ms

The following POA&M parameters/fields have the following character limitations:

To add (POST) POA&Ms use the following command:

$ bundle exec exe/emasser post poams add [-s, --systemId] <value> --status <value> --vulnerabilityDescription <value> --sourceIdentifyingVulnerability <value> --pocOrganization <value> --resources <value>

Notes:

If a milestone Id is provided (–milestone milestoneId:[value]) the POA&M with the provided milestone Id is updated and the new POA&M milestones is set to null.


Client API parameters/fields (required, conditional, and optional).

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post poams help add

top

post milestones


To add (POST) milestones in a system for one or more POA&M items use the following command:

  $ bundle exec exe/emasser post milestones add [-s, --systemId] <value> [-p, --poamId] <value> [-d, --description] <value> [c, --scheduledCompletionDate] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post milestones help add

top

post artifacts


The add (POST) artifacts endpoint accepts a single binary file with file extension.zip only. The command line (CI) reads the files provided and zips them before sending to eMASS.

If no artifact is matched via filename to the application, a new artifact will be created with the following default values. Any values not specified below will be blank.
  - isTemplate: false
  - type: other
  - category: evidence

Business Rules

$ bundle exec exe/emasser post artifacts upload [-s, --systemId] <value> [-f, --files] <value...value> [-B, --isBulk or --no-isBulk] -[-T, --isTemplate or --no-isTemplate] [-t, --type] <value> [-c, --category] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post artifacts help upload

top

post cac


Submit control to second role of CAC

Business Rule

To add (POST) test CAC use the following command:

  $ bundle exec exe/emasser post pac add [-s, --systemId] <value> [-a, --controlAcronym] <value> [-c, --comments] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post cac help add

top

post pac


Submit control to second role of CAC

To add (POST) test PAC use the following command:

  $ bundle exec exe/emasser post pac add [-s, --systemId] <value> [-f, --workflow] <value> [-n, --name] <value> [-c --comments] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post pac help add

top

post hardware


Add (POST) one or many hardware assets in a system.

  $ bundle exec exe/emasser post hardware add [-s, --systemId] <value> [-a, --assetName] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post hardware help add

top

post software


Add (POST) one or many software assets in a system.

  $ bundle exec exe/emasser post software add [-s, --systemId] <value> [-V --softwareVendor] <value> [-N, --softwareName] <value> [-v, --version] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post software help add

top

post device scan results

The body of a request through the Device Scan Results POST endpoint accepts a single binary file. Specific file extensions are expected depending upon the scanType parameter. For example, .ckl or .cklb files are accepted when using scanType is set to disaStigViewerCklCklb.

When set to acasAsrArf or policyAuditor, a .zip file is expected which should contain a single scan result (for example, a single pair of .asr and .arf files). Single files are expected for all other scan types as this endpoint requires files to be uploaded consecutively as opposed to in bulk.

Current scan types that are supported:

NOTE: The CLI accepts multiple files, adds them to a zip archive and submits to the endpoint.

To add a upload device scan results in the assets module for a system use the following command:

  $ bundle exec exe/emasser post device_scans  add -s, --systemId [value] -f, --filename [file1 file2 ...] -t, --scanType [type]

top

post cloud_resource


The following Cloud Resource parameters/fields have the following character limitations:

To add a cloud resource and their scan results in the assets module for a system use the following command:

  $ bundle exec exe/emasser post cloud_resource add -s, --systemId [value] --provider [value] --resourceId [value] --resourceName [value] --resourceType [value] --cspPolicyDefinitionId [value] --isCompliant or --is-not-Compliant --policyDefinitionTitle [value] --test [value]

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post cloud_resource help add

top

post container


The following Container parameters/fields have the following character limitations:

To add containers and their scan results in the assets module for a system use the following command:

  $ bundle exec ruby exe/emasser post container add -s, --systemId [value] --containerId [value] --containerName [value] --time [value] --benchmark [value] --lastSeen [value] --ruleId [value] --status [value]
 

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post container help add

top

post static_code_scan


To add (POST) static code scans use the following command:

  $ bundle exec exe/emasser post scan_findings add -s, --systemId [value] --applicationName [value] --version [value] --codeCheckName [value] --scanDate [value] --cweId [value]

*rawSeverity: In eMASS, values of “Critical” will appear as “Very High”, and values of “Medium” will appear as “Moderate”. Any values not listed as options in the list above will map to “Unknown” and appear as blank values.

To clear (POST) static code scans use the following command:

  $ bundle exec exe/emasser post scan_findings clear -s, --systemId [value] --applicationName [value] --version [value] --clearFindings

*The clearFindings field is an optional field, but required with a value of “True” to clear out all application findings for a single application/version pairing.

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser post scan_findings help add

top

Usage - PUT

put controls


Business Rules

The following fields are required based on the value of the implementationStatus field

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

Implementation Plan cannot be updated if a Security Control is “Inherited” except for the following fields:

The following parameters/fields have the following character limitations:

Implementation Plan information cannot be updated if Security Control does not exist in the system record.


Updating (PUT) a Control can be accomplished by invoking the following command:

  $ bundle exec exe/emasser put controls update [PARAMETERS]

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser put controls help update

top

put poams


Business Rules

The following fields are required based on the value of the status field

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

If a POC email is supplied, the application will attempt to locate a user already registered within the application and pre-populate any information not explicitly supplied in the request. If no such user is found, these fields are required within the request.

Business logic, the following rules apply when adding POA&Ms

The following parameters/fields have the following character limitations:

The following POA&M parameters/fields have the following character limitations:


Updating (PUT) a POA&M can be accomplished by invoking the following command:

  $ bundle exec exe/emasser put poams update [PARAMETERS]

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser put poams help update

top

put milestones


Updating (PUT) milestones in a system for one or more POA&M items use the following command:

  $ bundle exec exe/emasser post milestones update [-s, --systemId] <value> [-p, --poamId] <value> [-m, --milestoneId] <value> [-d, --description] <value> [c, --scheduledCompletionDate] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser put milestones help update

top

put artifacts


Business Rules

Updating (PUT) milestones in a system for one or more POA&M items use the following command:

  $ bundle exec exe/emasser put artifacts update [-s, --systemId] <value> [-f, --filename] <value> [-T, --isTemplate or --no-isTemplate] [-t, --type] <value> [-c, --category] <value> 

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser put artifacts help update

top

put hardware


Update (PUT) one or many hardware assets in a system.

  $ bundle exec exe/emasser post hardware add [-s, --systemId] <value> [-h, --hardwareId] <value> [-a, --assetName] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser put hardware help add

top

put software


Update (PUT) one or many software assets in a system.

  $ bundle exec exe/emasser post software update [-s, --systemId] <value> [-S --softwareId] <value> [-V, --softwareVendor] <value>  [-N, --softwareName] <value> [-v --version] <value>

Note For additional information about command line usages invoke the following help command:

$ bundle exec exe/emasser put software help add

top

Usage - DELETE

delete poams


Remove one or many poa&m items in a system

To remove (DELETE) one or more POA&M items use the following command:

$ bundle exec exe/emasser delete poams remove [-s, --systemId] <value> [-p, --poamId] <value>

top

delete milestones


Remove milestones in a system for one or many POA&M items

To delete a milestone the record must be inactive by having the field isActive set to false (isActive=false).

The server returns an empty object upon successfully deleting a milestone.

The last milestone can not be deleted, at-least on must exist.

To remove (DELETE) one or more Milestones in a system use the following command:

$ bundle exec exe/emasser delete milestones remove [-s, --systemId] <value> [-p, --poamId] <value> [-m, --milestoneId] <value>

top

delete artifacts


Remove one or many artifacts in a system

Provide single file or a space/comma delimited list of file names to be removed from the system (systemId)

To remove (DELETE) one or more Artifacts from a system use the following command:

Delete one file:
$ bundle exec exe/emasser delete artifacts remove [-s, --systemId] <value> [-f, --files] <value> 
Delete multiple files (can be space of comma delimited)
$ bundle exec exe/emasser delete artifacts remove [-s, --systemId] <value> [-f, --files] <value ... value>

top

delete hardware


Delete one or many one or multiple assets from a system Hardware Baseline for a system

To remove (DELETE) a hardware asset use the following command:

$ bundle exec exe/emasser delete hardware remove [-s, --systemId] <value> [-h, --hardwareIds] <value ... value>

top

delete software


Delete one or many one or multiple assets from a system Software Baselinefor a system

To remove (DELETE) a software asset use the following command:

$ bundle exec exe/emasser delete software remove [-s, --systemId] <value> [-w, --softwareIds] <value ... value>

top

delete cloud resource


Delete one or many Cloud Resources and their scan results in the assets module for a system

To remove (DELETE) one or many cloud resources in a system use the following command:

$ bundle exec exe/emasser delete cloud_resource remove [-s, --systemId] <value> [-r, --resourceId] <value>

top

delete container


Delete one or many containers scan results in the assets module for a system

To remove (DELETE) one or many containers in a system use the following command:

bundle exec exe/emasser delete container remove [-s, --systemId] <value> [-c, --containerId] <value>

top