diff --git a/Attestations/en/0x20-Standards.md b/Attestations/en/0x20-Standards.md index eea74dd..9f52080 100644 --- a/Attestations/en/0x20-Standards.md +++ b/Attestations/en/0x20-Standards.md @@ -11,20 +11,19 @@ In CDXA every requirement has: * External References ## Creating Your Own Standard -In CDXA, you're free to create your own security standard. It could be a subset or superset of an existing standard. There are a lot of good reasons to tailor a security standard to your particular system. But remember, you may be required to follow one or more external security standards. As we move into making claims and substantiating those claims in CDXA, you'll see how you can capture your approach to existing requirements to show compliance. +In CDXA, you're free to create your own security standard. It could be a subset or superset of an existing standard. +There are a lot of good reasons to tailor a security standard to your particular system. But remember, you may be +required to follow one or more external security standards. As we move into making claims and substantiating those +claims in CDXA, you'll see how you can capture your approach to existing requirements to show compliance. -# TODO - add links for CDXA versions of PCI SSS and OWASP SAMM | Original Standard | CDXA Version | | --- | --- | | [NIST Secure Software Development Framework (SSDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-218.pdf) | [CDXA-SSDF](https://github.com/CycloneDX/official-3rd-party-standards/blob/main/standards/NIST/SSDF/nist_secure-software-development-framework_1.1.cdx.json) | | [PCI Secure SLC Standard](https://docs-prv.pcisecuritystandards.org/Software%20Security/Standard/PCI-Secure-SLC-Standard-v1_1.pdf) | [CDXA-PCI-SSLC](https://github.com/CycloneDX/official-3rd-party-standards/blob/main/standards/PCI_Security_Standards_Council/Secure_SLC/pcissc-secure-slc-1.1.cdx.json) | -| [PCI Secure Software Standard](https://docs-prv.pcisecuritystandards.org/Software%20Security/Standard/PCI-Secure-Software-Standard-v1_2_1.pdf) | [CDXA-PCI-SSS](http://link.com) | | [Build Security In Maturity Model (BSIMM)](https://www.synopsys.com/software-integrity/resources/analyst-reports/bsimm.html) | [CDXA-BSIMM](https://github.com/CycloneDX/official-3rd-party-standards/blob/main/standards/BSIMM/bsimm-v13.cdx.json) | | [OWASP Application Security Verification Standard (ASVS)](https://github.com/OWASP/ASVS/raw/v4.0.3/4.0/OWASP%20Application%20Security%20Verification%20Standard%204.0.3-en.pdf) | [CDXA-OWASP-ASVS](https://github.com/CycloneDX/official-3rd-party-standards/blob/main/standards/OWASP/ASVS/asvs-4.0.3.cdx.json) | | [OWASP Mobile Application Security Verification Standard (MASVS)](https://github.com/OWASP/owasp-masvs/releases/latest/download/OWASP_MASVS.pdf) | [CDXA-OWASP-MASVS](https://github.com/CycloneDX/official-3rd-party-standards/blob/main/standards/OWASP/MASVS/masvs-2.0.0.cdx.json) | | [OWASP Software Component Verification Standard (SCVS)](https://scvs.owasp.org/scvs/) | [CDXA-OWASP-SCVS](scvs-1.0.0.cdx.json) | -| [OWASP Software Assurance Maturity Model (SAMM)](https://drive.google.com/file/d/1cI3Qzfrly_X89z7StLWI5p_Jfqs0-OZv/view?usp=sharing) | [CDXA-OWASP-SAMM](http://link.com) | -
\newpage diff --git a/Attestations/en/0x30-Making-Attestations.md b/Attestations/en/0x30-Making-Attestations.md index 95c73d1..cc7c510 100644 --- a/Attestations/en/0x30-Making-Attestations.md +++ b/Attestations/en/0x30-Making-Attestations.md @@ -1,18 +1,50 @@ # Making Attestations -TODO +CycloneDX Attestations (CDXA) represent a automated approach to enhancing security and compliance across various +standards. CycloneDX facilitates the representation of any standard—whether security-focused or otherwise—along with +the specific requirements associated with that standard. This capability ensures a broad applicability across different +domains and compliance needs. + +Building upon this foundational support, CycloneDX further empowers organizations by enabling them to make formal +attestations against these defined standards and requirements. These attestations are comprised of claims that are +supported by concrete evidence, providing a robust mechanism for demonstrating compliance or security posture. +Importantly, CycloneDX acknowledges the complexity of real-world scenarios by also accommodating counter-claims and +counter-evidence, thus fostering a comprehensive and nuanced view of compliance and security assessments. + +In instances where a requirement is not being fully met, CycloneDX's versatile framework allows for the specification of +mitigation strategies. This feature ensures that organizations can transparently communicate their efforts to address +potential shortcomings, thereby maintaining trust and integrity in the face of compliance challenges. Through these +capabilities, CycloneDX Attestations serve as a powerful tool for organizations striving to navigate the complex +compliance landscape with confidence and clarity. ## Claims -Claims are the way organizations can articulate their argument for meeting a particular requirement. You can break the requirement down into a set of claims that tackle some part of the overall requirement. There are many ways to structure your claims, but generally the simplest and most straightforward arguments are best. +Claims serve as the medium through which organizations can articulate their argument for meeting a specific requirement. You can dissect the requirement into a series of claims that address some part of the overall requirement. There are numerous ways to structure your claims, but it's important to remember that the simplest and most straightforward arguments often prove to be the most effective. + +For example, you may want to create a claim about each major module in a complex system. Or you might make claims about several separate aspects of a security defense. Sometimes, a single claim is enough to cover the entire requirement. + +A `Claim` is simply a statement that captures at least one aspect of how a certain requirement has been satisfied. A claim has two key parts: a target and a predicate. Claims often restate the requirement using specific terms related to the defenses in the system. -For example, you may want to create a claim about each major module in a complex system. Or you might make claims about several separate aspects of a security defense. In some cases, a single claim is enough to cover the entire requirement. +* `Target:` Each claim has a `target` that is the subject of the claim. The target might be the specific name of an entire system, a module, a process, a team, a business unit, or a company. In many cases, the target is simply an interpretation of the requirement for the current attestation. For example, the target might be "Acme Corporation" or "The Mxyzptlk Module." -A `Claim` is simply a statement that captures at least one aspect of how a certain requirement has been satisfied. A claim has two key parts, a target and a predicate. Claims often restate the requirement using specific terms related to the defenses in the system. +* `Predicate:` Each claim also has a `predicate` that states what is being claimed about the target. Once again, this is often a specific interpretation of the requirement that details exactly what was done to meet the requirement. For example, -* `Target:` Each claim has a `target` that is the subject of the claim. The target might be the specific name of entire system, a module, a process, a team, a business unit, or an entire company. In many cases, the target is simply an interpretation of the requirement for the current attestation. For example, the specifi might be "Acme Corporation" or "The Mxyzptlk Module." +The following table details the makeup of a claim. -* `Predicate:` Each claim also has a `predicate` that states what is being claimed about the target. Once again, this is often a specific interpretation of the requirement that details exactly what was done to meet the requirement. For example, +| Property | Description | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| bom-ref | An identifier, unique to the CDXA document, that identifies the claim. | +| target | The bom-ref to a target representing a specific system, application, API, module, team, person, process, business unit, company, etc... that this claim is being applied to. | +| predicate | The specific statement or assertion about the target. | +| mitigationStrategies | The list of bom-ref to the evidence provided describing the mitigation strategies. Each mitigation strategy should include an explanation of how any weaknesses in the evidence will be mitigated. | +| reasoning | The written explanation of why the evidence provided substantiates the claim. | +| evidence | The list of bom-ref to evidence that supports this claim. | +| counterEvidence | The list of bom-ref to counterEvidence that supports this claim. | + + +
+\emptyparagraph +
-For example, consider the requirement, "All developers must receive security training." An appropriate claim might be that "All members of the Acme development team have taken the HackMe Secure Coding for Java training course and received a passing grade on the final test." The target is "All members of the Acme development team" and the predicate is "have taken the HackMe Secure Coding for Java training course and received a passing grade on the final test." +For example, consider the requirement, "All developers must receive security training." An appropriate claim might be that "All members of the Acme development team have taken the HackMe Secure Coding for Java training course and received a passing grade on the final test." The target is "All members of the Acme development team," and the predicate is "have taken the HackMe Secure Coding for Java training course and received a passing grade on the final test." ```json "claims": [ @@ -35,4 +67,4 @@ For example, consider the requirement, "All developers must receive security tra
\newpage -
\ No newline at end of file +
diff --git a/Attestations/en/0x40-Substantiating-Claims-With-Evidence.md b/Attestations/en/0x40-Substantiating-Claims-With-Evidence.md index 76b2514..70c834c 100644 --- a/Attestations/en/0x40-Substantiating-Claims-With-Evidence.md +++ b/Attestations/en/0x40-Substantiating-Claims-With-Evidence.md @@ -16,7 +16,51 @@ Once we have a specific claim, we can consider the types of evidence that might * `Mitigation Strategy:` If the evidence is not compelling or counter evidence is present, the producer can detail their plans for improving conformance in this section. Ideally, the strategy should detail the change or enhancement, the rough schedule, and the expected effect on the evidence supporting the claim. -// TODO Small snippet for Evidence +The following table details the makeup of evidence. + +| Property | Description | +|--------------|-----------------------------------------------------------------------------------| +| bom-ref | An identifier, unique to the CDXA document, that identifies the evidence. | +| propertyName | The reference to the property name as defined in the CycloneDX Property Taxonomy. | +| description | The written description of what this evidence is and how it was created. | +| data | The output or analysis that supports claims. | +| created | The date and time (timestamp) when the evidence was created. | +| expires | The optional date and time (timestamp) when the evidence is no longer valid. | +| author | The author of the evidence. | +| reviewer | The reviewer of the evidence. | + + +```json +"evidence": [ + { + "bom-ref": "evidence-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Evidence here", + "contentType": "text/plain" + } + }, + "classification": "PII", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { "name": "Mary" }, + "reviewer": { "name": "Sanford" }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } +] +``` ## Reasoning @@ -26,7 +70,6 @@ Simply providing claims and evidence is not sufficient to determine whether the Your reasoning for a claim about not being susceptible to SQL injection might tie together several pieces of evidence (and address any counter evidence). For example, a strong argument would be that "Acme corporation policy, secure coding guidelines, and training progam ensure that developers are aware of SQL injection and how to prevent it. All database access is performed through Hibernate which uses parameterized SQL queries in most cases. We test our software for all types of SQL injection using IAST and have remediated all instances discovered. Finally, we use RASP in production to detect SQL injection attacks and prevent exploitation." -// TODO Small snippet for Reasoning ## Other @@ -34,7 +77,6 @@ Your reasoning for a claim about not being susceptible to SQL injection might ti * `Signature:` Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html). -// TODO Small snippet that ties everything together ## Another Example diff --git a/Attestations/en/0x60-Signing.md b/Attestations/en/0x60-Signing.md index e5caabd..d3b4190 100644 --- a/Attestations/en/0x60-Signing.md +++ b/Attestations/en/0x60-Signing.md @@ -81,4 +81,6 @@ The following are examples of digital signatures in a CycloneDX attestation: ``` - +
+\newpage +
diff --git a/Attestations/en/0x70-Example.md b/Attestations/en/0x70-Example.md new file mode 100644 index 0000000..f4704b4 --- /dev/null +++ b/Attestations/en/0x70-Example.md @@ -0,0 +1,215 @@ +# Example + +The following is a full example of a CycloneDX attestation. + +```json +{ + "bomFormat": "CycloneDX", + "specVersion": "1.6", + "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79", + "version": 1, + "declarations": { + "assessors": [ + { + "bom-ref": "assessor-1", + "thirdParty": true, + "organization": { + "name": "Assessors Inc" + } + } + ], + "attestations": [ + { + "summary": "Attestation summary here", + "assessor": "assessor-1", + "map": [ + { + "requirement": "requirement-1", + "claims": [ "claim-1" ], + "counterClaims": [ "counterClaim-1" ], + "conformance": { + "score": 0.8, + "rationale": "Conformance rationale here", + "mitigationStrategies": [ "mitigationStrategy-1" ] + }, + "confidence": { + "score": 1, + "rationale": "Confidence rationale here" + } + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ], + "claims": [ + { + "bom-ref": "claim-1", + "target": "acme-inc", + "predicate": "Predicate here", + "mitigationStrategies": [ "mitigationStrategy-1" ], + "reasoning": "Reasoning here", + "evidence": [ "evidence-1" ], + "counterEvidence": [ "counterEvidence-1" ], + "externalReferences": [ + { + "type": "issue-tracker", + "url": "https://alm.example.com" + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ], + "evidence": [ + { + "bom-ref": "evidence-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Evidence here", + "contentType": "text/plain" + } + }, + "classification": "PII", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { + "name": "Mary" + }, + "reviewer": { + "name": "Jane" + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + { + "bom-ref": "counterEvidence-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Counter evidence here", + "contentType": "text/plain" + } + }, + "classification": "Public", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { + "name": "Mary" + }, + "reviewer": { + "name": "Jane" + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + { + "bom-ref": "mitigationStrategy-1", + "propertyName": "internal.com.acme.someProperty", + "description": "Description here", + "data": [ + { + "name": "Name of the data", + "contents": { + "attachment": { + "content": "Mitigation strategy here", + "contentType": "text/plain" + } + }, + "classification": "Company Confidential", + "sensitiveData": [ "Describe sensitive data here" ] + } + ], + "created": "2023-04-25T00:00:00+00:00", + "expires": "2023-05-25T00:00:00+00:00", + "author": { + "name": "Mary" + }, + "reviewer": { + "name": "Jane" + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + } + ], + "targets": { + "organizations": [ + { + "bom-ref": "acme-inc", + "name": "Acme Inc" + } + ] + }, + "affirmation": { + "statement": "I certify, to the best of my knowledge, that all information is correct...", + "signatories": [ + { + "name": "Tom", + "role": "CEO", + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + { + "name": "Jerry", + "role": "COO", + "organization": { + "name": "Acme Inc" + }, + "externalReference": { + "type": "electronic-signature", + "url": "https://example.com/coo-sig.png" + } + } + ], + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } + }, + "signature": { + "algorithm": "ES256", + "certificatePath": [ "MIIB...", "MIID..." ], + "value": "tqIT..." + } +} +``` \ No newline at end of file