emasser CLI Features and Capabilities

Environment Variables

To facilitate setting the required environment variables the emasser SAF CLI utilized the zero-dependency module to load these variables from a .env file. See Generating an eMASS Configuration 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 Environment Variables

The following environment variables are required:

Optional Environment Variables

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:

[VARIABLE_NAME]='value'

NOTE

The emasser commands requires access to an eMASS instance. Authentication and authorization to an eMASS instance is not a function of emasser and needs to be accomplished with the eMASS instance owner organization. Further information about eMASS credential requirements refer to Defense Counterintelligence and Security Agency about eMASS access.

Fo instruction on how to request an eMASS visit eMASS Account Process Request and API Registration

Common emasser Endpoint Requests Information

API Endpoints Provided

GET

POST

PUT

DELETE

Generating an eMASS Configuration File

Provided with the eMASS API CLI is an interactive command line user interface for generating the configuration file .env required to connect to an eMASS instance(s).

Generate a configuration file (.env) for accessing an eMASS instance(s).

USAGE
  $ saf emasser configure

DESCRIPTION
  Generate a configuration file (.env) for accessing an eMASS instances.

  The following variables are required:
  EMASSER_API_KEY           <The eMASS API key (api-key) - valid key is > 30 alpha numeric characters>
  EMASSER_USER_UID          <The eMASS User Unique Identifier (user-uid)>
  EMASSER_HOST_URL          <The Full Qualified Domain Name (FQDN) for the eMASS server>
  EMASSER_KEY_FILE_PATH     <The eMASS key.pem private encrypting the key in PEM format (file, include the path)>
  EMASSER_CERT_FILE_PATH    <The eMASS cert.pem containing the certificate information in PEM format (file, include the path)>
  EMASSER_KEY_FILE_PASSWORD <The password for the private encryption key.pem file>

  The following variables are optional, if not provided defaults are used:
  EMASSER_PORT                <The server communication port number (default is 443)>
  EMASSER_REQUEST_CERT        <Server requests a certificate from connecting clients - true or false (default true)>
  EMASSER_REJECT_UNAUTHORIZED <Reject clients with invalid certificates - true or false (default true)>
  EMASSER_DEBUGGING           <Set debugging on (true) or off (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)>

EXAMPLES
  $ saf emasser configure

Endpoints CLI help

To view eMASS API top help (available topics & commands) use the following command:

$ saf emasser [-h or -help]
[eMASS]        The eMASS REST API implementation

USAGE
  $ saf emasser COMMAND

TOPICS
  emasser delete  eMass REST API DELETE endpoint commands
  emasser get     eMass REST API GET endpoint commands
  emasser post    eMass REST API POST endpoint commands
  emasser put     eMass REST API PUT endpoint commands

COMMANDS
  emasser configure  Generate a configuration file (.env) for accessing an eMASS instance(s).
  emasser version    Display the eMASS API specification version the CLI implements.

Each CLI endpoint command have several layers of help.

Command line flags

All command line flags have a short and long option, for example: -s or –systemId can be use as:

-s 36 or --systemId 36

Boolean true/false flags do NOT take an argument, they are reversed with --no- value. If we have a flag name isTemplate it would be uses as:

--isTemplate (true) --no-isTemplate (false)

Usage - GET

get test connection

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

$ 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 retrieves a single system defined by the ID (systemId).

Get system information for a specific system defined by ID (systemId)

USAGE
  $ saf emasser get system [options]

FLAGS
  -h, --help                 Show emasser CLI help for the GET System endpoint
  -s, --systemId=<value>     (required) The system identification number  
  -I, --[no-]includePackage  Boolean - include system packages
  -p, --policy=<option>      Filter on policy
                             <options: diacap|rmf|reporting>

DESCRIPTION
  Get system information for a specific system defined by ID (systemId)

EXAMPLES
  $ saf emasser get system [-s, --systemId] <value> [options]

top

get systems

The get systems command retrieves all available system defined by the ID (systemId) and filter by available options.

Get available systems filter on provided options

USAGE
  $ saf emasser get systems [options]

FLAGS
  -h, --help                        Show emasser CLI help for the GET Systems endpoint
  -D, --[no-]includeDecommissioned  Boolean - include decommissioned systems
  -I, --[no-]includePackage         Boolean - include system packages
  -M, --[no-]includeDitprMetrics    Boolean - include DoD Information Technology metrics
  -S, --[no-]reportsForScorecard    Boolean - include score card
  -c, --coamsId=<value>             Cyber Operational Attributes Management System (COAMS) string Id
  -p, --policy=<option>             Filter on policy <options: diacap|rmf|reporting>
  -r, --registrationType=<option>   Filter on registration type
                                    <options: assessAndAuthorize|assessOnly|guest|regular|functional|cloudServiceProvider|commonControlProvider>
  -t, --ditprId=<value>             DoD Information Technology (IT) Portfolio Repository (DITPR) string Id

DESCRIPTION
  Get available systems filter on provided options

EXAMPLES
  $ saf emasser get systems [options]

top

get roles

There are two endpoints for system roles - all and byCategory

USAGE
  $ saf emasser get roles [ARGUMENT]

ARGUMENTS
  all         Retrieves all available system roles
  byCategory  Retrieves role(s) - filtered by [options] params

FLAGS
  -h, --help  Show emasser CLI help for the GET Roles endpoint

DESCRIPTION
  Retrieve all available system roles, or filter by options

EXAMPLES
  $ saf emasser get roles all

  $ saf emasser get roles byCategory [-c, --roleCategory] <value> [-r, --role] <value> [options]

top

get controls

Get system Security Control information for both the Implementation Plan and Risk Assessment

USAGE
  $ saf emasser get controls [options]

FLAGS
  -h, --help              Show emasser CLI help for the GET Controls endpoint
  -s, --systemId=<value>  (required) The system identification number
  -A, --[no-]acronyms     The system acronym(s) e.g "AC-1, AC-2" - if not provided all controls for systemId are returned

DESCRIPTION
  Get system Security Control information for both the Implementation Plan and Risk Assessment

EXAMPLES
  $ saf emasser get controls --systemId <value> [option]

top

get test_results

Get test results for a specific system defined by ID (systemId)

USAGE
  $ saf emasser get test_results [options]

FLAGS
  -h, --help                     Show emasser CLI help for the GET Test Results endpoint
  -s, --systemId=<value>         (required) The system identification number
  -L, --[no-]latestOnly          Boolean - Filter on latest only
  -a, --controlAcronyms=<value>  The system acronym(s) e.g "AC-1, AC-2"
  -c, --ccis=<value>             The system CCIS string numerical value

DESCRIPTION
  Get test results for a specific system defined by ID (systemId)

EXAMPLES
  $ saf emasser get test_results --systemId <value> [options]

top

get poams

There are two endpoints for system poams forSystem and byPoamId

top

get milestones

There are two endpoints for system milestones byPoamId and byMilestoneId

top

get artifacts

There are two endpoints for artifacts forSystem and export

top

get cac

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

  USAGE
    $ saf emasser get cac [options]

  FLAGS
    -h, --help                     Show emasser CLI help for the GET CAC endpoint
    -s, --systemId=<value>         (required) The system identification number  
    -a, --controlAcronyms=<value>  The system acronym(s) e.g "AC-1, AC-2"

  DESCRIPTION
    View one or many Control Approval Chain (CAC) in a system specified system ID

  EXAMPLES
    $ saf emasser get cac --systemId <value>

top

get pac

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

  USAGE
    $ saf emasser get pac [options]

  FLAGS
    -h, --help              Show emasser CLI help for the GET PAC endpoint
    -s, --systemId=<value>  (required) The system identification number

  DESCRIPTION
    View one or many Package Approval Chain (PAC) in a system specified system ID

  EXAMPLES
    $ saf emasser get pac --systemId <value>

top

get cmmc

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

  USAGE
    $ saf emasser get cmmc [options]

  FLAGS
    -h, --help               Show emasser CLI help for the GET CMMC endpoint  
    -d, --sinceDate=<value>  (required) The CMMC date. Unix date format

  DESCRIPTION
    View Cybersecurity Maturity Model Certification (CMMC) Assessments

  EXAMPLES
    $ saf emasser get cmmc --sinceDate <value>

top

get workflow_definitions

To view Workflow Definitions use the following command:

  USAGE
    $ saf emasser get workflow_definitions [options]

  FLAGS
    -h, --help                       Show emasser CLI help for the GET Workflow Definitions endpoint
    -i, --[no-]includeInactive       Boolean - Include inactive workflows
    -r, --registrationType=<option>  The registration type - must be a valid type
                                    <options: assessAndAuthorize|assessOnly|guest|regular|functional|cloudServiceProvider|commonControlProvider>

  DESCRIPTION
    View all workflow schemas available on the eMASS instance

  EXAMPLES
    $ saf emasser get workflow_definitions [options]

top

get workflow_instances

There are two endpoints to view workflow instances all and byInstanceId

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.

USAGE
  $ saf emasser get dashboards [ARGUMENT]

ARGUMENTS
  status_details                  Get systems status detail dashboard information
  control_compliance_summary      Get control compliance summary dashboard information
  security_control_details        Get security control details dashboard information
  assessment_procedures_details   Get assessment procedures details dashboard information
  poam_summary                    Get systems POA&Ms summary dashboard information
  poam_details                    Get system POA&Ms details dashboard information
  artifacts_summary               Get artifacts summary dashboard information
  artifacts_details               Get artifacts details dashboard information
  hardware_summary                Get hardware summary dashboard information
  hardware_details                Get hardware details dashboard information
  sensor_hardware_summary         Get sensor hardware summary dashboard information
  sensor_hardware_details         Get sensor hardware details dashboard information
  software_summary                Get software baseline summary dashboard information
  software_details                Get software baseline details dashboard information
  ports_protocols_summary         Get ports and protocols summary dashboard information
  ports_protocols_details         Get ports and protocols details dashboard information
  integration_status_summary      Get CONMON integration status summary dashboard information
  associations_details            Get system associations details dashboard information
  assignments_details             Get user system assignments details dashboard information
  privacy_summary                 Get system privacy summary dashboard information
  fisma_saop_summary              Get VA OMB-FISMA SAOP summary dashboard information
  va_aa_summary                   Get VA system A&A summary dashboard information
  va_a2_summary                   Get VA system A2.0 summary dashboard information
  va_pl_109_summary               Get VA System P.L. 109 reporting summary dashboard information
  fisma_inventory_summary         Get VA system FISMA inventory summary dashboard information
  fisma_inventory_crypto_summary  Get VA system FISMA inventory summary dashboard information
  va_threat_risk_summary          Get VA threat risk summary dashboard information
  va_threat_source_details        Get VA threat source details dashboard information
  va_threat_architecture_details  Get VA threat architecture details dashboard information

FLAGS
  -h, --help                  Show emasser CLI help for the GET Dashboards endpoint
  -I, --[no-]excludeInherited Boolean - exclude inherited data (default false)
  -i, --pageIndex=<value>     The index of the starting page (default first page 0)
  -o, --orgId=<value>         (required) The organization identification number
  -s, --pageSize=<value>      The number of entries per page (default 20000)

DESCRIPTION
  Retrieves a pre-defined dashboard by orgId

EXAMPLES
  $ saf emasser get dashboards [dashboard name] [flag] [options]

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

Available commands are:

top

Usage - POST

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

Add (POST) test results CLI usage

  USAGE
    $ saf emasser post test_results [options]

  FLAGS
    -h, --help                       Post (add) test results to a system's Assessment Procedures (CCIs)
    -s, --systemId=<value>           (required) The system identification number
    -t, --testDate=<value>           (required) The date test was conducted, Unix time format  
    -b, --testedBy=<value>           (required) The person that conducted the test (Last Name, First)
    -c, --cci=<value>                (required) The system CCI string numerical value
    -d, --description=<value>        (required) The description of test result. 4000 Characters    
    -S, --complianceStatus=<option>  (required) The system CCI string numerical value
                                    <options: Compliant|Non-Compliant|Not Applicable>

  DESCRIPTION
    Add test results for a system's Assessment Procedures (CCIs) which determine Security Control compliance

  EXAMPLES
    $ saf emasser post test_results [-s,--systemId] [-c,--cci] [-b,--testedBy] [-t,--testDate] [-d,--description] [-S,--complianceStatus]

Note: If no POA&Ms or AP exist for the control (system), the following message is returned: “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.”

top

post poams

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

Requirements based on status field value

status 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

POC fields requirements

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 for adding POA&Ms

POA&M parameters/fields character limitations

Add (POST) POA&Ms CLI usages

USAGE
  $ saf emasser post poams [options]

FLAGS
  -h, --help              Post (add) a Plan of Action and Milestones (POA&M) item(s) in a system. See emasser Features (emasserFeatures.md) for additional information.
  -s, --systemId=<value>  (required) The system identification number
  -f, --poamFile=<value>  (required) A well formed JSON file with the POA&M(s) to be added to the specified system. It can ba a single object or an array of objects.

DESCRIPTION
  Add a Plan of Action and Milestones (POA&M) into a systems.

EXAMPLES
  $ saf emasser post poams [-s,--systemId] [-f,--poamFile]

Note: The input file should be a well formed JSON containing the POA&M information based on defined business rules.

Required JSON parameter/fields are:

  {
    "status": "One of the following: [Ongoing, Risk Accepted, Completed, Not Applicable]",
    "vulnerabilityDescription": "POA&M vulnerability description",
    "sourceIdentVuln": "Source that identifies the vulnerability",
    "pocOrganization": "Organization/Office represented",
    "resources": "List of resources used"
  }

Conditional JSON parameters/fields are:

  {
    "milestones": [
      {
        "description": "The milestone description",
        "scheduledCompletionDate": "Milestone scheduled completion date (Unix format)"
      }
    ],
    "pocFirstName": "The system acronym(s) e.g AC-1, AC-2",
    "pocLastName": "The system CCIS string numerical value",
    "pocEmail": "Security Checks that are associated with the POA&M",
    "pocPhoneNumber": "One of the following [I, II, III]",
    "severity": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "scheduledCompletionDate": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "completionDate": "Description of Security Control impact",
    "comments": "Description of the security control impact"
  }

Optional JSON parameters/fields

  {
    "externalUid": "External ID associated with the POA&M",
    "controlAcronym": "The system acronym(s) e.g AC-1, AC-2",
    "cci": "The system CCIS string numerical value",
    "securityChecks": "Security Checks that are associated with the POA&M",
    "rawSeverity": "One of the following [I, II, III]",
    "relevanceOfThreat": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "likelihood": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "impact": "Description of Security Control impact",
    "impactDescription": "Description of the security control impact",
    "residualRiskLevel": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "recommendations": "Any recommendations content",
    "mitigation": "Mitigation explanation"
  }

top

post milestones

Add (POST) milestones to one or many POA&M items in a system

USAGE
  $ saf emasser post milestones [options]

FLAGS
  -h, --help                             Post (add) milestones to one or many POA&M items in a system
  -p, --poamId=<value>                   (required) The poam identification number
  -s, --systemId=<value>                 (required) The system identification number
  -c, --scheduledCompletionDate=<value>  (required) The scheduled completion date - Unix time format
  -d, --description=<value>              (required) The milestone description

DESCRIPTION
  Add milestones to one or many POA&M items in a system

EXAMPLES
  $ saf emasser post milestones [-s,--systemId] [-p,--poamId] [-d,--description] [-c,--scheduledCompletionDate]

top

post artifacts

Upload artifacts one or many artifacts in a system

The body of a request through the Artifacts POST endpoint accepts a single binary file with extension “.zip” only. This .zip file should contain one or more files corresponding to existing artifacts or new artifacts that will be created upon successful receipt. Filename uniqueness within an eMASS system will be enforced by the API.

Business rules

Upon successful receipt of a file, if a file within the .zip is matched via filename to an artifact existing within the application, the file associated with the artifact will be updated. If no artifact is matched via filename to the application, a new artifact will be created with the following default values.

  - isTemplate: false
  - type: other
  - category: evidence

Any values not specified below will be null.

Accepted artifact files are:

Artifacts rules and limitations

Add (POST) Artifacts CLI usages

USAGE
  $ saf emasser post artifacts [options]

FLAGS
  -h, --help               Post (add) artifact file(s) to a system
  -i, --input=<value>...   (required) Artifact file(s) to post to the given system, can have multiple (space separated)
  -s, --systemId=<value>   (required) The system identification number
  -T, --[no-]isTemplate    Boolean - Indicates whether an artifact is a template.
  -c, --category=<option>  Artifact category <options: Implementation Guidance|Evidence>
  -t, --type=<option>      Artifact file type <options: Procedure|Diagram|Policy|Labor|Document|Image|Other|Scan Result|Auditor Report>

DESCRIPTION
  Uploads [FILES] to the given [SYSTEM_ID] as artifacts

EXAMPLES
  $ saf emasser post artifacts [-s,--systemId] [-i,--input] [options]

top

post cac

Add a Control Approval Chain (CAC) items in a system

Business Rule

Add (POST) CAC CLI usages

USAGE
  $ saf emasser post cac [options]

FLAGS
  -h, --help                    Post (add) control to second stage of CAC
  -s, --systemId=<value>        (required) The system identification number
  -a, --controlAcronym=<value>  (required) The system acronym "AC-1, AC-2"
  -c, --comments=<value>        The control approval chain comments

DESCRIPTION
  Add a Control Approval Chain (CAC) items in a system

EXAMPLES
  $ saf emasser post cac [-s,--systemId] [-a,--controlAcronym] [options]

top

post pac

Add new Package Approval Chain (PAC) workflow(s) for a system

Add (POST) PAC CLI usages

USAGE
  $ saf emasser post pac [options]

FLAGS
  -h, --help               Post (add) a Package Approval Chain (PAC) item in a system
  -s, --systemId=<value>   (required) The system identification number  
  -c, --comments=<value>   (required) The control approval chain comments
  -n, --name=<value>       (required) The control package name
  -w, --workflow=<option>  (required) The appropriate workflow
                           <options: Assess and Authorize|Assess Only|Security Plan Approval>

DESCRIPTION
  Add new Package Approval Chain (PAC) workflow(s) for a system

EXAMPLES
  $ saf emasser post pac [-s,--systemId] [-w,--workflow] [-n,--name] [-c,--comments]

top

post static_code_scans

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

USAGE
  $ saf emasser post static_code_scans [options]

FLAGS
  -h, --help                       Post (upload) static code scans, can also clear application's findings
  -s, --systemId=<value>           (required) The system identification number
  -f, --statiCodeScanFile=<value>  (required) A well formed JSON file with application scan findings. It can ba a single object or an array of objects.

DESCRIPTION
  upload application scan findings into a system's assets module

EXAMPLES
  $ saf emasser post static_code_scans [-s,--systemId] [-f,--cloudResourceFile]

Note: The input file [-f,--statiCodeScanFile] should be a well formed JSON containing application scan findings.

Required application JSON object parameter/fields are:

  {
    "applicationName": "Name of the software application that was assessed",
    "version": "The version of the application"
  }

Required applicationFindings JSON array parameters/fields are:

  {
    "applicationFindings": [
      {
        "codeCheckName": "Name of the software vulnerability or weakness",
        "scanDate": "The scan date, Unix date format",
        "resourceName": "Friendly name of Cloud resource",
        "cweId": "The Common Weakness Enumerator (CWE) identifier",
        "count": "Number of instances observed for a specified finding",
        "rawSeverity": "OPTIONAL - One of the following [Low, Medium, Moderate, High, Critical]"
      }
    ]
  }

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

  $ saf emasser post static_code_scans [-s,--systemId] [-f,--cloudResourceFile]

With the following JSON content:

  {
    "application": {
      "applicationName": "Name of the software application that was assessed",
      "version": "The version of the application"
    },
    "applicationFindings": [
      {
        "clearFindings": true
      }
    ]
  }

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

top

post cloud_resource

Add Cloud Resource Results scans in the assets module for a system.

Cloud Resource parameters/fields character limitations

Add (POST) Cloud Resources CLI usages

USAGE
  $ saf emasser post cloud_resources [options]

FLAGS
  -h, --help                       Post (add) cloud resources and their scan results in the assets module for a system
  -s, --systemId=<value>           (required) The system identification number
  -f, --cloudResourceFile=<value>  (required) A well formed JSON file with the cloud resources and their scan results. It can ba a single object or an array of objects.

DESCRIPTION
  Add a cloud resource and their scan results in the assets module for a system

EXAMPLES
  $ saf emasser post cloud_resources [-s,--systemId] [-f,--cloudResourceFile]

Note: The input file [-f, --cloudResourceFile]should be a well formed JSON containing the cloud resources and their scan results information.

Required JSON parameter/fields are:

  {
    "provider": "Cloud service provider name",
    "resourceId": "Unique identifier/resource namespace for policy compliance result",
    "resourceName": "Friendly name of Cloud resource",
    "resourceType": "The cloud resource type",
    "complianceResults": [
      {
        "cspPolicyDefinitionId": "Unique identifier/compliance namespace for CSP/Resource's policy definition/compliance check",
        "isCompliant": "True/false flag for compliance status of the policy for the identified cloud resource",
        "policyDefinitionTitle": "Friendly policy/compliance check title. Recommend short title"
      }
    ]
  }

Optional JSON parameters/fields are:

  {
    "cspAccountId": "System/owner's CSP account ID/number",
    "cspRegion": "CSP region of system",
    "initiatedBy": "Email of POC",
    "isBaseline": "True/false flag for providing results as baseline. If true, all existing compliance results for the resourceId will be replaced by results in the current call",
    "tags": {
      "test": "Informational tags associated to results for other metadata"
    },
    "complianceResults": [
      {
        "assessmentProcedure": "Comma separated correlation to Assessment Procedure (i.e. CCI number for DoD Control Set)",
        "complianceCheckTimestamp": "Unix date format",
        "complianceReason": "Reason/comments for compliance result",
        "control": "Comma separated correlation to Security Control (e.g. exact NIST Control acronym)",
        "policyDeploymentName": "Name of policy deployment",
        "policyDeploymentVersion": "Version of policy deployment",
        "severity": "One of the following [Low, Medium, High, Critical]"
      }
    ]
  }

top

post container_scans

Add Container Scan Results in the assets module for a system.

Container Scan Results parameters/fields character limitations

Add (POST) Container Scan Results CLI usages

USAGE
  $ saf emasser post container_scans [options]

FLAGS
  -h, --help                           Post (upload) one or many containers and their scan results for a system
  -s, --systemId=<value>               (required) The system identification number
  -f, --containerCodeScanFile=<value>  (required) A well formed JSON file with container scan results. It can ba a single object or an array of objects.

DESCRIPTION
  Upload containers and their scan results in the assets module for a system

EXAMPLES
  $ saf emasser post container_scans [-s,--systemId] [-f,--containerCodeScanFile]

Note: The input file [-f, --containerCodeScanFile] should be a well formed JSON containing the container scan results information.

Required JSON parameter/fields are:

  {
    "containerId": "Unique identifier of the container",
    "containerName": "Friendly name of the container",
    "time": "Datetime of scan/result. Unix date format",
    "benchmarks": [
      {
        "benchmark": "Identifier of the benchmark/grouping of compliance results. (e.g. for STIG results, provide the benchmark id for the STIG technology)",
        "results": [
          {
            "ruleId": "Identifier for the compliance result, vulnerability, etc. the result is for. (e.g. for STIGs, use the SV-XXXrXX identifier; for CVEs, the CVE-XXXX-XXX identifier, etc.).",
            "lastSeen": "Datetime last seen. Unix date format",
            "status": "One of the following [Pass,Fail,Other,Not Reviewed,Not Checked,Not Applicable]"
          }
        ]
      }
    ]
  }

Optional JSON parameters/fields are:

  {
    "namespace": "Namespace of container in container orchestration (e.g. Kubernetes namespace)",
    "podIp": "IP address of pod (e.g. Kubernetes assigned IP)",
    "podName": "Name of pod (e.g. Kubernetes pod)",
    "tags": {
      "test": "Informational tags associated to results for other metadata"
    },
    "benchmarks": [
      {
        "isBaseline": "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",
        "results": [
          {
            "message": "Comments for the result"
          }
        ]
      }
    ]
  }

top

Usage - PUT

put controls

Security Control update (PUT) endpoint API business rules.

Requirements based on implementationStatus field value

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:

Security Controls parameters/fields character limitations

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

Update (PUT) System Controls CLI usages

USAGE
  $ saf emasser put controls [options]

FLAGS
  -h, --help                 Put (update) control information in a system for one or many controls. See emasser Features (emasserFeatures.md) for additional information.
  -s, --systemId=<value>     (required) The system identification number
  -f, --controlFile=<value>  (required) A well formed JSON file with the Security Control information to be updated to the specified system. It can ba a single object or an array of objects.

DESCRIPTION
  Update Security Control information of a system for both the Implementation Plan and Risk Assessment.

EXAMPLES
  $ saf emasser put controls [-s,--systemId] [-f,--controlsFile]

Note: The input file should be a well formed JSON containing the Security Control information based on defined business rules.

Required JSON parameter/fields are:

  {
    "acronym": "System acronym, required to match the NIST SP 800-53 Revision 4.",
    "responsibleEntities": "Include written description of Responsible Entities that are responsible for the Security Control.",
    "controlDesignation": "One of the following: [Common, System-Specific, Hybrid]",
    "estimatedCompletionDate": "Field is required for Implementation Plan",
    "implementationNarrative": "Includes Security Control comments"
  }

Conditional JSON parameters/fields are:

  {
    "commonControlProvider": "One of the following [DoD, Component, Enclave]",
    "naJustification": "Provide justification for Security Controls deemed Not Applicable to the system",
    "slcmCriticality": "Criticality of Security Control regarding SLCM",
    "slcmFrequency": "One of the following [Constantly,Daily,Weekly,Monthly,Quarterly,Semi-Annually,Annually,Every Two Years,Every Three Years,Undetermined]",
    "slcmMethod": "One of the following [Automated, Semi-Automated, Manual, Undetermined]",
    "slcmReporting": "Organization/Office represented",
    "slcmTracking": "The System-Level Continuous Monitoring tracking",
    "slcmComments": " Additional comments for Security Control regarding SLCM"
  }

Optional JSON parameters/fields are:

  {
    "implementationStatus": "One of the following [Planned,Implemented,Inherited,Not Applicable,Manually Inherited]",
    "severity": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "vulnerabilitySummary": "Include vulnerability summary",
    "recommendations": "The include recommendations",
    "relevanceOfThreat": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "likelihood": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "impact": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "impactDescription": "Include description of Security Controls impact",
    "residualRiskLevel": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "testMethod": "One of the following [Test, Interview, Examine, Test,Interview, Test,Examine, Interview,Examine, Test,Interview,Examine]"
  }

top

put poams

Plan of Action and Milestones (POA&M) update (PUT) endpoint API business rules.

Requirements based on status field value

status 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

POC fields requirements

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 for updating POA&Ms

The following parameters/fields have the following character limitations:

POA&M parameters/fields character limitations

Updating (PUT) POA&Ms CLI usages

USAGE
  $ saf emasser put poams [options]

FLAGS
  -h, --help              Put (update) a Plan of Action and Milestones (POA&M) item(s) in a system. See emasser Features (emasserFeatures.md) for additional information.
  -s, --systemId=<value>  (required) The system identification number
  -f, --poamFile=<value>  (required) A well formed JSON file with the POA&M(s) to be updated to the specified system. It can ba a single object or an array of objects.

DESCRIPTION
  Update a Plan of Action and Milestones (POA&M) into a systems.

EXAMPLES
  $ saf emasser put poams [-s,--systemId] [-f,--poamFile]

Note: The input file should be a well formed JSON containing the POA&M information based on defined business rules.

Required JSON parameter/fields are:

  {
    "poamId": "Unique identifier representing the nth POAM item entered into the site database.",
    "displayPoamId": "Globally unique identifier for individual POA&M Items, seen on the front-end as ID",
    "status": "One of the following: [Ongoing, Risk Accepted, Completed, Not Applicable]",
    "vulnerabilityDescription": "POA&M vulnerability description",
    "sourceIdentVuln": "Source that identifies the vulnerability",
    "pocOrganization": "Organization/Office represented",
    "resources": "List of resources used"
  }

Conditional JSON parameters/fields are:

  {
    "milestones": [
      {
        "milestoneId": "Unique milestone identifier",
        "description": "The milestone description",
        "scheduledCompletionDate": "Milestone scheduled completion date (Unix format)",
        "isActive": "To prevent uploading duplicate/undesired milestones through the POA&M PUT you must include an isActive field for the milestone and set it to equal to false"
      }
    ],
    "pocFirstName": "The system acronym(s) e.g AC-1, AC-2",
    "pocLastName": "The system CCIS string numerical value",
    "pocEmail": "Security Checks that are associated with the POA&M",
    "pocPhoneNumber": "One of the following [I, II, III]",
    "severity": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "scheduledCompletionDate": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "completionDate": "Description of Security Control impact",
    "comments": "Description of the security control impact"
  }

Optional JSON parameters/fields are:

{
    "externalUid": "External ID associated with the POA&M",
    "controlAcronym": "The system acronym(s) e.g AC-1, AC-2",
    "cci": "The system CCIS string numerical value",
    "securityChecks": "Security Checks that are associated with the POA&M",
    "rawSeverity": "One of the following [I, II, III]",
    "relevanceOfThreat": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "likelihood": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "impact": "Description of Security Control impact",
    "impactDescription": "Description of the security control impact",
    "residualRiskLevel": "One of the following [Very Low, Low, Moderate, High, Very High]",
    "recommendations": "Any recommendations content",
    "mitigation": "Mitigation explanation"
  }

top

put milestones

Update (PUT) one or many milestones for a POA&M items in a system

USAGE
  $ saf emasser put milestones [options]

FLAGS
  -h, --help                             Show emasser CLI help for the PUT Milestones endpoint
  -s, --systemId=<value>                 (required) The system identification number
  -p, --poamId=<value>                   (required) The poam identification number
  -m, --milestoneId=<value>              (required) Unique milestone identifier
  -c, --scheduledCompletionDate=<value>  The scheduled completion date - Unix time format
  -d, --description=<value>              The milestone description

DESCRIPTION
  Update milestone(s) for specified system, poam, and milestone Id

EXAMPLES
  $ saf emasser put milestones [-s,--systemId] [-p,--poamId] [-m,--milestoneId] [-d,--description] [-c,--scheduledCompletionDate]

top

put artifacts

Update one or many artifacts in a system

Accepted artifact files are:

Update (PUT) Artifacts CLI usages

USAGE
  $ saf emasser put artifacts [options]

FLAGS
  -h, --help                            Put (update) one or many artifacts in a system
  -s, --systemId=<value>                (required) The system identification number
  -f, --filename=<value>                (required) Artifact file name to update for the given system
  -T, --[no-]isTemplate                 (required) Boolean - Indicates whether an artifact is a template.
  -g, --category=<option>               (required) Artifact category <options: Implementation Guidance|Evidence>
  -t, --type=<option>                   (required) Artifact file type
                                        <options: Procedure|Diagram|Policy|Labor|Document|Image|Other|Scan Result|Auditor Report>
  -d, --description=<value>             The artifact(s) description
  -p, --refPageNumber=<value>           Artifact reference page number
  -c, --ccis=<value>                    CCIs associated with artifact
  -C, --controls=<value>                Control acronym associated with the artifact. NIST SP 800-53 Revision 4 defined.
  -D, --artifactExpirationDate=<value>  Date artifact expires and requires review
  -R, --lastReviewDate=<value>          Date artifact was last reviewed

DESCRIPTION
  Updates artifacts for a system with provided entries

EXAMPLES
  $ saf emasser put artifacts [-s,--systemId] [-f,--filename] [--isTemplate,--no-isTemplate] [-t,--type] [-g--category] [options]

top

Usage - DELETE

delete poams

Remove (DELETE) POA&Ms CLI usages

USAGE
  $ saf emasser delete poams [options]

FLAGS
  -h, --help                Show emasser CLI help for the DELETE POA&M endpoint
  -s, --systemId=<value>    (required) The system identification number
  -P, --poamsId=<value>...  (required) Unique POA&M identification number, can have multiple (space separated)

DESCRIPTION
  Remove one or many POA&M items in a system identified by system and poam Id

EXAMPLES
  $ saf emasser delete poams [-s,--systemId] [-P,--poamsId]

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 last milestone can not be deleted, at-least on must exist.

Remove (DELETE) Milestones CLI usages

USAGE
  $ saf emasser delete milestones [options]

FLAGS
  -h, --help                     Show emasser CLI help for the DELETE Milestones endpoint
  -s, --systemId=<value>         (required) The system identification number
  -p, --poamId=<value>           (required) The poam identification number
  -M, --milestonesId=<value>...  (required) Unique milestone identifier, can have multiple (space separated)

DESCRIPTION
  Remove milestones in a system for one or many POA&M items identified by system, poam, and milestone Id

EXAMPLES
  $ saf emasser delete milestones [-s,--systemId] [-p,--poamId] [-M,--milestonesId]

Note Multiple milestones can be deleted by including multiple milestone Ids separated by a space.

top

delete artifacts

Remove one or many artifacts in a system

Remove (DELETE) Artifact files CLI usages

USAGE
  $ saf emasser delete artifacts [options]

FLAGS
  -h, --help                 Show emasser CLI help for the DELETE POA&M endpoint
  -s, --systemId=<value>     (required) The system identification number
  -F, --fileName=<value>...  (required) The artifact file name to remove, can have multiple (space separated)

DESCRIPTION
  Remove one or many artifacts in a system identified by system Id

EXAMPLES
  $ saf emasser delete artifacts [-s,--systemId] [-F,--fileName]

Note Multiple artifacts can be deleted by including multiple file names separated by a space.

top