JupiterOne integrates with and consolidates data from several security and compliance solutions right out of the box (for example, ingesting security assessments and findings from AWS Inspector, GuardDuty, Veracode, WhiteHat, and more).
However, there will inevitably be operational and compliance artifacts produced outside of automated tools, such as Assessments performed manually (E.G. risk assessments or penetration tests) and the Findings and Risks identified by those assessments.
These efforts are typically documented in unstructured formats (Word or PDF) or are maintained in a separate repository such as a governance, risk and compliance (GRC), or vulnerability management system/software/service (VMS).
JupiterOne serves as a lightweight GRC and VMS so that no separate, siloed tools are needed, allowing teams to manage security and compliance artifacts as code.
TL;DR 
Ok. Here's some example code. Dive in!
https://github.com/JupiterOne/secops-automation-examples
Security artifacts as code 
Instead of writing security documents in Word, which are difficult to track and maintain, you should create and store artifacts and records as code. You can then easily upload these artifacts to JupiterOne for querying and reporting. Check out the examples below!
Note that the following properties are common across all entity types:
entityId
The JupiterOne API does not require this property. If it is not provided, JupiterOne will create a new entity for the document. If it is provided, JupiterOne will update the existing entity for that id.
entityKey
This property is required and must be unique. The JupiterOne entity creation API will update any existing entity with an identical key.
entityType
,entityClass
,name
,displayName
These properties are required.
All other properties listed in the examples are recommended but not required.
You can create documents to upload to JupiterOne in either JSON or YAML format. We use YAML in the examples below because it makes dealing with long, multi-line text much easier.
Assessment Entity Example
--- - entityId: entityKey: assessment:hipaa:2018 entityType: risk_assessment entityClass: Assessment properties: name: HIPAA Risk Assessment 2018 displayName: company-hipaa-risk-assessment-2018 summary: 2018 Annual HIPAA Risk Assessment description: (sample text) Organization's security and compliance team assessed policies, controls and procedures to ensure they meet and exceed the requirements specified by HIPAA privacy rule and security rule. details: additional report details category: risk-assessment status: complete assessors: - security.staff@yourcompany.com - internal.audit@yourcompany.com open: false classification: confidential completedOn: 2018-07-23 reportURL: <link to full report> webLink: <link to full report> - entityId: entityKey: assessment:pentest:2019q1 entityType: penetration_test entityClass: Assessment properties: name: internal-pen-test-2019q1 displayName: Company Internal Penetration Test 2019Q1 summary: Company Internal Penetration Test Q1 2019 conducted between Mar 18th - Mar 29th description: (sample text) Performed a thorough security assessment of the company product line. Scope includes product A, B and C. details: additional report details category: penetration-testing status: complete assessors: - pen.tester1@yourcompany.com - pen.tester2@yourcompany.com open: false classification: confidential completedOn: 2019‑04‑05
The above example contains an array of two assessment objects - one HIPAA Risk
Assessment and one Internal Penetration Test. If there is a more detailed report
stored elsewhere, such as on your company's SharePoint or Google Docs account,
you can link to it using the reportURL
and webLink
properties. The webLink
property is known by the JupiterOne UI and will render a hyperlink.
We recommend also writing a full report in Markdown and storing that in source
code control. The reportURL
/ webLink
in that case will be something like
this:
https://bitbucket.org/yourorg/security-assessments/src/master/2018/hipaa-risk-assessment-report.md
When you specify the email address(es) of the assessor(s), JupiterOne looks
up those individuals (the Person
entities) and creates the following mapped
relationship:
Person (with matching email address) - PERFORMED -> Assessment
Risk Entity Example
--- - entityId: entityKey: risk:endpoint-management-gaps entityType: technical_risk entityClass: Risk properties: name: Endpoint management gaps displayName: Endpoint management gaps summary: Lack of visibility on how user endpoint systems/devices are configured description: (sample text) Endpoint systems should be configured according to the company's IT and security standards. Because currently all enduser systems (e.g. laptops) are self managed, there is a lack of centralized visibility into how each system is configured and if they meet the compliance requirements details: 'Systems should be configured with at least the following:' 1. Disk encryption enabled 2. Screensaver protection/screen lock on 3. Local firewall enabled 4. Remote login disabled 5. Auto install OS security patches enabled 6. (if it is Windows) Has Windows Defender or equivalent malware protection running category: technical threats: malware targets: enduser devices probability: 2 impact: 2 score: 4 status: open reporter: security@yourcompany.com open: true mitigation: jiraKey: SEC-112 webLink: https://yourcompany.atlassian.net/browse/SEC-112
Notes:
The Risk
score
=probability
timesimpact
Both
probability
andimpact
are numeric values, between 0-3. (you may choose to use a different scale)Probability rating:
3: high/certain
2: medium/likely
1: low/unlikely
0: none/negligible
Impact rating:
3: high/severe
2: medium/moderate
1: low/minor
0: none/insignificant
Example valid Risk
status
:accepted
mitigated
transferred
reported
planned
acknowledged
prioritized
The Risk is considered
open
unless it isaccepted
,mitigated
ortransferred
status.When uploaded to JupiterOne, Risks will automatically map to an employee/Person using the email address specified in the
reporter
property:
Person (with matching email address) - REPORTED -> Risk
- Similarly, specify the assessment name in the
assessment
property to create the following mapping:
Assessment (with matching name) - IDENTIFIED -> Risk
The
webLink
property is optional.Note the
jiraKey
property and thewebLink
URL in the example point to a Jira issue since Jira is used to track the workflow of this Risk item.
Finding Entity Example
A vulnerability finding is similar to a risk item:
--- - entityId: entityKey: finding:pentest:2019q1:appcode-1 entityType: pentest_finding entityClass: Finding properties: name: XSS in application {appname} displayName: XSS in application {appname} summary: Stored cross side scripting identified in application {appname} targets: - appname description: description of the finding stepsToReproduce: - '1 - Sign in to application... navigate to page...' - '2 - Enter <script>alert(1)</script> in textbox...' - '3 - Hit save...' impact: Attacker may store malicious javascript... recommendation: Perform input validation in the code... severity: high priority: 2 remediationSLA: 30 status: open assessment: internal-pen-test-2019q1 open: true classification: confidential jiraKey: SEC-99 webLink: https://yourcompany.atlassian.net/browse/SEC-99
Again, the assessment
property here is used to connect the finding to the
assessment that identified it.
Additionally, if the targets
property contains one or more entries that match
the name
of an Application
/CodeRepo
/Project
entity, this finding
will be linked to that matching entity, so that you can easily run a query like:
Find (Application|CodeRepo|Project) that has Finding with severity='high'
Also note the remediationSLA
property. This specifies the number of days your
team has left to address this finding per your company policy.
Uploading to JupiterOne 
Once you have created your artifacts, you can easily upload them to JupiterOne using the CLI. Just follow these three simple steps:
Obtain an API Key from your JupiterOne account
Install JupiterOne client/CLI:
npm install @jupiterone/jupiterone-client-nodejs -g
- Upload the artifacts (entities) to your account on JupiterOne:
export J1_API_TOKEN={api_key} j1 -o create --entity -a {accountId} -f ./risks.yml j1 -o create --entity -a {accountId} -f ./assessments.yml j1 -o create --entity -a {accountId} -f ./findings.yml
If you have several YAML files to upload, you might use a command like:
export J1_API_TOKEN={api_key} find . -name \*.yml | while read yml; do j1 -o create --entity -a <j1_account_id> -f $yml; done
We highly recommended you use a source code control system such as Github or Bitbucket to maintain these artifacts. This way, you can easily set up your CI system (e.g. Travis CI or Jenkins) to run the above commands and automatically keep the entities up to date in JupiterOne with every approved code change (i.e. when a PR is merged into master).
Reporting and Visualization
You can see and export these Assessments, Risks, and Findings from the Asset Inventory app in JupiterOne or query and visualize them on the Landing page.
Query:
Find Person that performed Assessment that identified (Risk|Finding) return tree
Graph:
Lastly, these artifacts are automatically tracked and mapped to the supported compliance requirements as evidences for conducting the necessary assessments.
PDF:
You can use a simple utility to query J1 for an assessment, its related
findings, and generate a PDF report. An example can be found in the
secops-automation-examples
Github repo:
Comments
1 comment
555-555-0199@example.com
Please sign in to leave a comment.