Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
Using JupiterOne as a central repository for SecOps and compliance artifacts - AskJ1 Community
<main> <article class="userContent"> <p>JupiterOne integrates with and consolidates data from several security and<br> compliance solutions right out of the box (for example, ingesting security<br> assessments and findings from AWS Inspector, GuardDuty, Veracode, WhiteHat, and<br> more).</p> <p>However, there will inevitably be operational and compliance artifacts produced<br> outside of automated tools, such as <strong>Assessments</strong> performed manually<br> (E.G. risk assessments or penetration tests) and the <strong>Findings</strong> and <strong>Risks</strong><br> identified by those assessments.</p> <p>These efforts are typically documented in unstructured formats (Word or PDF) or<br> are maintained in a separate repository such as a governance, risk and<br> compliance (GRC), or vulnerability management system/software/service (VMS).</p> <p>JupiterOne serves as a lightweight GRC and VMS so that no separate, siloed tools<br> are needed, allowing teams to manage security and compliance artifacts as code.</p> <h2 data-id="tl-dr">TL;DR</h2> <p><em>Ok. Here's some example code. Dive in!</em></p> <p><a rel="nofollow" href="https://github.com/JupiterOne/secops-automation-examples">https://github.com/JupiterOne/secops-automation-examples</a></p> <h2 data-id="security-artifacts-as-code">Security artifacts as code</h2> <p>Instead of writing security documents in Word, which are difficult to track and<br> maintain, you should create and store artifacts and records as code. You can<br> then easily upload these artifacts to JupiterOne for querying and<br> reporting. Check out the examples below!</p> <p>Note that the following properties are common across all entity types:</p> <ul><li><p><code class="code codeInline" spellcheck="false" tabindex="0">entityId</code></p> <p>The JupiterOne API does not require this property. If it is not provided,<br> JupiterOne will create a new entity for the document. If it is provided,<br> JupiterOne will update the existing entity for that id.</p></li> <li><p><code class="code codeInline" spellcheck="false" tabindex="0">entityKey</code></p> <p>This property is required and must be unique. The JupiterOne entity creation<br> API will update any existing entity with an identical key.</p></li> <li><p><code class="code codeInline" spellcheck="false" tabindex="0">entityType</code>, <code class="code codeInline" spellcheck="false" tabindex="0">entityClass</code>, <code class="code codeInline" spellcheck="false" tabindex="0">name</code>, <code class="code codeInline" spellcheck="false" tabindex="0">displayName</code></p> <p>These properties are required.</p></li> </ul><p>All other properties listed in the examples are recommended but not required.</p> <p>You can create documents to upload to JupiterOne in either JSON or YAML<br> format. We use YAML in the examples below because it makes dealing with long,<br> multi-line text much easier.</p> <h3 data-id="assessment-entity-example"><strong>Assessment</strong> Entity Example</h3> <pre class="code codeBlock" spellcheck="false" tabindex="0">--- - 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 </pre> <p>The above example contains an array of two assessment objects - one HIPAA Risk<br> Assessment and one Internal Penetration Test. If there is a more detailed report<br> stored elsewhere, such as on your company's SharePoint or Google Docs account,<br> you can link to it using the <code class="code codeInline" spellcheck="false" tabindex="0">reportURL</code> and <code class="code codeInline" spellcheck="false" tabindex="0">webLink</code> properties. The <code class="code codeInline" spellcheck="false" tabindex="0">webLink</code><br> property is known by the JupiterOne UI and will render a hyperlink.</p> <p>We recommend also writing a full report in Markdown and storing that in source<br> code control. The <code class="code codeInline" spellcheck="false" tabindex="0">reportURL</code> / <code class="code codeInline" spellcheck="false" tabindex="0">webLink</code> in that case will be something like<br> this:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">https://bitbucket.org/yourorg/security-assessments/src/master/2018/hipaa-risk-assessment-report.md </pre> <p>When you specify the email address(es) of the assessor(s), JupiterOne looks<br> up those individuals (the <code class="code codeInline" spellcheck="false" tabindex="0">Person</code> entities) and creates the following mapped<br> relationship:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">Person (with matching email address) - PERFORMED -> Assessment </pre> <h3 data-id="risk-entity-example"><strong>Risk</strong> Entity Example</h3> <pre class="code codeBlock" spellcheck="false" tabindex="0">--- - 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 </pre> <p>Notes:</p> <ul><li><p>The Risk <code class="code codeInline" spellcheck="false" tabindex="0">score</code> = <code class="code codeInline" spellcheck="false" tabindex="0">probability</code> times <code class="code codeInline" spellcheck="false" tabindex="0">impact</code></p> <ul><li><p>Both <code class="code codeInline" spellcheck="false" tabindex="0">probability</code> and <code class="code codeInline" spellcheck="false" tabindex="0">impact</code> are numeric values, between 0-3.<br> (you may choose to use a different scale)</p></li> <li><p>Probability rating:</p></li> <li><p>3: high/certain</p></li> <li>2: medium/likely</li> <li>1: low/unlikely</li> <li><p>0: none/negligible</p></li> <li><p>Impact rating:</p></li> <li><p>3: high/severe</p></li> <li>2: medium/moderate</li> <li>1: low/minor</li> <li>0: none/insignificant</li> </ul></li> <li><p>Example valid Risk <code class="code codeInline" spellcheck="false" tabindex="0">status</code>:</p> <ul><li><code class="code codeInline" spellcheck="false" tabindex="0">accepted</code></li> <li><code class="code codeInline" spellcheck="false" tabindex="0">mitigated</code></li> <li><code class="code codeInline" spellcheck="false" tabindex="0">transferred</code></li> <li><code class="code codeInline" spellcheck="false" tabindex="0">reported</code></li> <li><code class="code codeInline" spellcheck="false" tabindex="0">planned</code></li> <li><code class="code codeInline" spellcheck="false" tabindex="0">acknowledged</code></li> <li><code class="code codeInline" spellcheck="false" tabindex="0">prioritized</code></li> </ul></li> <li><p>The Risk is considered <code class="code codeInline" spellcheck="false" tabindex="0">open</code> unless it is <code class="code codeInline" spellcheck="false" tabindex="0">accepted</code>, <code class="code codeInline" spellcheck="false" tabindex="0">mitigated</code> or<br><code class="code codeInline" spellcheck="false" tabindex="0">transferred</code> status.</p></li> <li><p>When uploaded to JupiterOne, Risks will automatically map to an<br> employee/Person using the email address specified in the <code class="code codeInline" spellcheck="false" tabindex="0">reporter</code> property:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">Person (with matching email address) - REPORTED -> Risk </pre></li> <li><p>Similarly, specify the assessment name in the <code class="code codeInline" spellcheck="false" tabindex="0">assessment</code> property to create<br> the following mapping:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">Assessment (with matching name) - IDENTIFIED -> Risk </pre></li> <li><p>The <code class="code codeInline" spellcheck="false" tabindex="0">webLink</code> property is optional.</p></li> <li><p>Note the <code class="code codeInline" spellcheck="false" tabindex="0">jiraKey</code> property and the <code class="code codeInline" spellcheck="false" tabindex="0">webLink</code> URL in the example point to a<br> Jira issue since Jira is used to track the workflow of this Risk item.</p></li> </ul><h3 data-id="finding-entity-example"><strong>Finding</strong> Entity Example</h3> <p>A vulnerability finding is similar to a risk item:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">--- - 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 </pre> <p>Again, the <code class="code codeInline" spellcheck="false" tabindex="0">assessment</code> property here is used to connect the finding to the<br> assessment that identified it.</p> <p>Additionally, if the <code class="code codeInline" spellcheck="false" tabindex="0">targets</code> property contains one or more entries that match<br> the <code class="code codeInline" spellcheck="false" tabindex="0">name</code> of an <code class="code codeInline" spellcheck="false" tabindex="0">Application</code>/<code class="code codeInline" spellcheck="false" tabindex="0">CodeRepo</code>/<code class="code codeInline" spellcheck="false" tabindex="0">Project</code> entity, this finding<br> will be linked to that matching entity, so that you can easily run a query like:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">Find (Application|CodeRepo|Project) that has Finding with severity='high' </pre> <p>Also note the <code class="code codeInline" spellcheck="false" tabindex="0">remediationSLA</code> property. This specifies the number of days your<br> team has left to address this finding per your company policy.</p> <h2 data-id="uploading-to-jupiterone">Uploading to JupiterOne</h2> <p>Once you have created your artifacts, you can easily upload them to JupiterOne<br> using the CLI. Just follow these three simple steps:</p> <ol><li><p>Obtain an API Key from your JupiterOne account</p></li> <li><p>Install JupiterOne client/CLI:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">npm install @jupiterone/jupiterone-client-nodejs -g </pre></li> <li><p>Upload the artifacts (entities) to your account on JupiterOne:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">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 </pre> <p>If you have several YAML files to upload, you might use a command like:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">export J1_API_TOKEN={api_key} find . -name \*.yml | while read yml; do j1 -o create --entity -a <j1_account_id> -f $yml; done </pre></li> </ol><p>We highly recommended you use a source code control system such as Github or<br> Bitbucket to maintain these artifacts. This way, you can easily set up your CI<br> system (e.g. Travis CI or Jenkins) to run the above commands and automatically<br> keep the entities up to date in JupiterOne with every approved code change (i.e.<br> when a PR is merged into master).</p> <h3 data-id="reporting-and-visualization">Reporting and Visualization</h3> <p>You can see and export these Assessments, Risks, and Findings from the Asset<br> Inventory app in JupiterOne or query and visualize them on the Landing page.</p> <p><strong>Query:</strong></p> <pre class="code codeBlock" spellcheck="false" tabindex="0">Find Person that performed Assessment that identified (Risk|Finding) return tree </pre> <p><strong>Graph:</strong></p> <p><img src="https://us.v-cdn.net/6035534/uploads/PQD2QOQ70JJI/graph-person-performed-pentest-findings.png" alt="pentest-findings" class="embedImage-img importedEmbed-img"></img></p> <p>Lastly, these artifacts are automatically tracked and mapped to the supported<br> compliance requirements as evidences for conducting the necessary assessments.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/RX3IWZGE01D4/compliance-risk-assessments.png" alt="risk-assessments" class="embedImage-img importedEmbed-img"></img></p> <p><strong>PDF:</strong></p> <p>You can use a simple utility to query J1 for an assessment, its related<br> findings, and generate a PDF report. An example can be found in the<br><code class="code codeInline" spellcheck="false" tabindex="0">secops-automation-examples</code> Github repo:</p> <p><a rel="nofollow" href="https://github.com/JupiterOne/secops-automation-examples">https://github.com/JupiterOne/secops-automation-examples</a></p> </article> </main>
.png)