Promote scorecards with OWASP Top 10 examples #2649
Conversation
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
|
Fixing typos and making minor improvements soon. ETA: 11th Monday 12 Noon AEST. Please do not merge |
There was a problem hiding this comment.
rename the file to follow the same file naming conventions (ie begin with small letters, like examples.md)
|
|
||
| - [Dora Metrics based on number of deployments](/promote-scorecards/examples/dora-metrics-deployments/) | ||
| - [Ensure relation exists](/promote-scorecards/examples/relation-existence/) | ||
| - [Ownership scorecard](/promote-scorecards/examples/Ownership-scorecard/) | ||
| - [Owasp Top 10](/promote-scorecards/examples/Owasp-Top10/) No newline at end of file |
There was a problem hiding this comment.
This looks odd, Can we have a section for examples in the promote scorecard page, and then the link will lead to this page.
It will also be good if they were cards. the page looks weird with just the links
| # Owasp Top 10 Scorecard | ||
|
|
||
| <img src="/img/guides/owasp/chart.png" width="80%" border="1px" alt="OWASP Top 10 Chart showing Gold, Silver and Basic tier distribution" /> | ||
|
|
There was a problem hiding this comment.
add a line break here to detach the bottom context a bit slightly from the image
| 1. Repository – The primary entity where the Scorecard will reside. | ||
| 2. Snyk Target – Contains entities that will be evaluated against 10 rules, each corresponding to an entry in the OWASP Top 10. | ||
| 3. Snyk Vulnerability – Contains entities representing individual vulnerabilities of various types. |
There was a problem hiding this comment.
You should move this to prerequisite and reference the integrations that need to be setup for this documentation. So user's before hand know which integrations are needed to follow through with this example
| 2. Snyk Target – Contains entities that will be evaluated against 10 rules, each corresponding to an entry in the OWASP Top 10. | ||
| 3. Snyk Vulnerability – Contains entities representing individual vulnerabilities of various types. | ||
|
|
||
| **Prerequisites:** |
There was a problem hiding this comment.
Change to a header tag
Prerequisite
| - GitHub / SCM – Repositories must be onboarded to Snyk and listed in the Portal Catalog. | ||
| - Snyk – The Exporter must be configured in your portal. |
There was a problem hiding this comment.
There's a way we put this.
This guide assumes you have a Port account and that you have finished the onboarding process.
Install Port's GitHub app
Install Port's Snyk integration
| #### Snyk Vulnerability | ||
|
|
||
| To accurately benchmark against the OWASP Top 10 for code, most static analysis tools support generating Common Weakness Enumeration (CWE) IDs. If CWEs are not yet included in your blueprint, you can add them to the Snyk Vulnerability blueprint by following these steps: | ||
| - Navigate to the Builder. | ||
| - Go to Data Sources. | ||
| - Under Exporters for Snyk, select Snyk Vulnerability Blueprint. | ||
| - In the Mapping section, under the vulnerability kind, add the following property mapping. | ||
|
|
||
| ```json showLineNumbers | ||
| cwe: .attributes.classes[0].id | ||
| ``` | ||
| 5. Resync data from Snyk exporter. | ||
| 6. Navigate to catalog table to confirm that CWEs are now visible. | ||
|
|
||
| #### Snyk Target | ||
|
|
||
| - The Snyk Vulnerability and Snyk Target entities are connected through both the Snyk Target ID (via Snyk Target) and the Snyk Project ID (via Snyk Project). | ||
| - Now that CWEs are available, we can leverage the Snyk Target blueprint to classify security issues and group them by CWE categories, following the OWASP Top 10 framework. | ||
| - Accordingly, the Snyk Target blueprint can be updated to support classification of vulnerabilities under the OWASP Top 10(http://owasp.org/Top10), as demonstrated in L300–L774. | ||
| - The objective is to create 10 dedicated properties within Snyk Target, each corresponding to one of the OWASP Top 10 categories for code. | ||
|
|
||
| <details> | ||
| <summary><b>Snyk Target Blueprint reference</b></summary> | ||
| ```json showLineNumbers | ||
| { | ||
| "identifier": "snykTarget", | ||
| "title": "Snyk Target", | ||
| "icon": "Snyk", | ||
| "schema": { | ||
| "properties": { |
There was a problem hiding this comment.
Move all the blueprint related setup to a header called ## Set up data model
| To accurately benchmark against the OWASP Top 10 for code, most static analysis tools support generating Common Weakness Enumeration (CWE) IDs. If CWEs are not yet included in your blueprint, you can add them to the Snyk Vulnerability blueprint by following these steps: | ||
| - Navigate to the Builder. | ||
| - Go to Data Sources. | ||
| - Under Exporters for Snyk, select Snyk Vulnerability Blueprint. | ||
| - In the Mapping section, under the vulnerability kind, add the following property mapping. | ||
|
|
||
| ```json showLineNumbers | ||
| cwe: .attributes.classes[0].id | ||
| ``` | ||
| 5. Resync data from Snyk exporter. | ||
| 6. Navigate to catalog table to confirm that CWEs are now visible. |
There was a problem hiding this comment.
Move this to a separate header called update data source and let the blueprint setup come before the mapping update happens
…or-code' of https://github.com/port-labs/port-docs into promote-scorecards/examples#benchmarking-owasp-top-10-for-code
…sp-top-10-for-code
…or-code' of https://github.com/port-labs/port-docs into promote-scorecards/examples#benchmarking-owasp-top-10-for-code
…sp-top-10-for-code
…sp-top-10-for-code
|
Claude finished @udayk-port's task —— View job PR Review Complete ✅Reviewing PR #2649: "Promote scorecards with OWASP Top 10 examples" Todo List:
📋 Overall AssessmentThis PR adds a comprehensive OWASP Top 10 scorecard example to the documentation, which is valuable content. However, there are several issues that need to be addressed to meet Port's documentation standards. 🎯 Major Issues1. File Organization & Structure
2. OWASP Section IssuesThe OWASP Top 10 section has several structural problems: Prerequisites Section (lines 164-167)❌ Current format: <h2>Prerequisites</h2>
- This example assumes you have a Port account...✅ Should be: ## Prerequisites
This guide assumes you have a Port account and that you have finished the [onboarding process](https://docs.port.io/getting-started/overview).
**Required integrations:**
- Install Port's [GitHub app](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/#setup)
- Install Port's [Snyk integration](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/code-quality-security/snyk/)Content Structure Issues
3. Writing Style & Tone IssuesInconsistent Voice (Line 157)❌ Current: "This section explains how to build..." British vs American Spelling (Line 1046)❌ Current: "customised", "organisation's" Typo (Line 1051)❌ Current: "security weaknesss" 4. Technical Content IssuesFormatting Standards
Link and Reference Issues
📝 Detailed Line-by-Line Review
🔧 RecommendationsHigh Priority
Medium Priority
Low Priority
✅ Positive Aspects
🚧 Previous Review Comments StatusAddressed:
Still Need Attention:
🎯 Action Items
This PR contains valuable content but needs these formatting and structural improvements to meet Port's documentation standards. |
…or-code' of https://github.com/port-labs/port-docs into promote-scorecards/examples#benchmarking-owasp-top-10-for-code
…sp-top-10-for-code
…sp-top-10-for-code
…or-code' of https://github.com/port-labs/port-docs into promote-scorecards/examples#benchmarking-owasp-top-10-for-code
|
Claude encountered an error —— View job I'll analyze this and get back to you. |
…sp-top-10-for-code
kodjomiles
left a comment
kodjomiles
left a comment
There was a problem hiding this comment.
Looks good overall, left some few comments and suggestions
docs/promote-scorecards/examples.md
Outdated
|
|
||
| <h3>Snyk Target</h3> | ||
|
|
||
| With the addition of the `CWE` property to the `Snyk Vulnerability` blueprint, you can now classify vulnerabilities by CWE and align them with the [OWASP Top 10](http://owasp.org/Top10) categories. |
There was a problem hiding this comment.
| With the addition of the `CWE` property to the `Snyk Vulnerability` blueprint, you can now classify vulnerabilities by CWE and align them with the [OWASP Top 10](http://owasp.org/Top10) categories. | |
| With the addition of the `CWE` property to the `Snyk Vulnerability` blueprint, you can now classify vulnerabilities by CWE and align them with the [OWASP Top 10](http://owasp.org/Top10) categories. | |
docs/promote-scorecards/examples.md
Outdated
|
|
||
| 2. Click on the `Snyk Target` blueprint. | ||
|
|
||
| 3. Click on the `...` button in the top right corner, choose `Edit blueprint`, then click on the `{...} Edit JSON` button. |
There was a problem hiding this comment.
We can head straight to {...} Edit JSON without going to Edit blueprint first
docs/promote-scorecards/examples.md
Outdated
|
|
||
| 3. Click on the `...` button in the top right corner, choose `Edit blueprint`, then click on the `{...} Edit JSON` button. | ||
|
|
||
| 4. Update the existing JSON by incorporating the following data in it, then click `Save`. |
There was a problem hiding this comment.
| 4. Update the existing JSON by incorporating the following data in it, then click `Save`. | |
| 4. Update the aggregation property to include the snippet JSON snippet below: |
There was a problem hiding this comment.
Since it's just the aggregation property we are adding we can be specific. so the user knows exactly where to put this json snippet
docs/promote-scorecards/examples.md
Outdated
| <h3>Repository</h3> | ||
|
|
||
| The `Snyk Target` blueprint should have a defined relation with the `GitHub Repository` blueprint. | ||
| If your current model does not include a relation from the `Repository` blueprint to the `Snyk Target` blueprint, add it. |
There was a problem hiding this comment.
If the relation is a high dependency then we might want to show them how to add that relation
docs/promote-scorecards/examples.md
Outdated
| The `Snyk Target` blueprint should have a defined relation with the `GitHub Repository` blueprint. | ||
| If your current model does not include a relation from the `Repository` blueprint to the `Snyk Target` blueprint, add it. | ||
|
|
||
| The next step is to add the OWASP identifiers as mirrored properties to the `GitHub Repository` blueprint, and update the mapping configuration so that each `GitHub Repository` is automatically linked to its corresponding `Snyk Target`. This link is what allows the mirrored OWASP properties to pull their values from the related Snyk data. |
There was a problem hiding this comment.
| The next step is to add the OWASP identifiers as mirrored properties to the `GitHub Repository` blueprint, and update the mapping configuration so that each `GitHub Repository` is automatically linked to its corresponding `Snyk Target`. This link is what allows the mirrored OWASP properties to pull their values from the related Snyk data. | |
| The next step is to add the OWASP identifiers as mirrored properties to the `GitHub Repository` blueprint, and update the mapping configuration so that each `GitHub Repository` is automatically linked to its corresponding `Snyk Target`. | |
| This link is what allows the mirrored OWASP properties to pull their values from the related Snyk data. |
docs/promote-scorecards/examples.md
Outdated
|
|
||
| 2. Click on the `GitHub Repository` blueprint. | ||
|
|
||
| 3. Click on the `...` button in the top right corner, choose `Edit blueprint`, then click on the `{...} Edit JSON` button. |
There was a problem hiding this comment.
| 3. Click on the `...` button in the top right corner, choose `Edit blueprint`, then click on the `{...} Edit JSON` button. | |
| 3. Click on the `...` button in the top right corner and click on the `{...} Edit JSON` button. |
docs/promote-scorecards/examples.md
Outdated
|
|
||
| 3. Click on the `...` button in the top right corner, choose `Edit blueprint`, then click on the `{...} Edit JSON` button. | ||
|
|
||
| 4. Update the existing JSON by incorporating the following data in it, then click `Save`. |
There was a problem hiding this comment.
| 4. Update the existing JSON by incorporating the following data in it, then click `Save`. | |
| 4. Update the mirrorProperties to include the snippet below: |
There was a problem hiding this comment.
Updating the entire JSON would cause inconvenience if the user has other mirror properties or the user might end up replacing the entire JSON with the snippet we are providing
…or-code' of https://github.com/port-labs/port-docs into promote-scorecards/examples#benchmarking-owasp-top-10-for-code
…sp-top-10-for-code
sivanel97
deleted the
promote-scorecards/examples#benchmarking-owasp-top-10-for-code
branch
Description
Added docs pages
The following paths have been added
Updated docs pages
This path now has a new page markdown under the folder structure to help accomodate more sub-sections