Feature: add 21 uncontested Gemara lexicon terms - #103
Conversation
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
| @@ -1,11 +1,15 @@ | |||
| acceptance | |||
There was a problem hiding this comment.
the wordlist only needs to include exceptions that are failing in the spellchecker. it does not need to include all of the terms of the glossary itself. if a term in the glossary is passing the spellchecker it doesnt need to be added here.
There was a problem hiding this comment.
Done @GeauxJD, just fixed the wordlist to only include non-english words, awaiting your approval 👍
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR migrates an initial batch of Gemara lexicon definitions into the OpenSSF Glossary by adding 21 new term pages, along with small supporting updates for spellcheck and site assets.
Changes:
- Added 21 new glossary term markdown files (Gemara lexicon batch).
- Updated
wordlist.txtto whitelist “gemara” for CI spellcheck. - Normalized/adjusted a couple of existing files (
content/en/dast.md, CSS imports, andpackage-lock.json).
Reviewed changes
Copilot reviewed 23 out of 25 changed files in this pull request and generated 21 comments.
Show a summary per file
| File | Description |
|---|---|
| wordlist.txt | Adds “gemara” to the spellcheck allowlist. |
| themes/docsy/static/css/shortcodes.css | Keeps Docsy shortcode CSS imports consistent. |
| package-lock.json | Lockfile metadata update (adds peer: true in a couple of package entries). |
| content/en/dast.md | Minor formatting adjustment to the Source line placement. |
| content/en/sensitive-activity.md | New term page: Sensitive Activity. |
| content/en/rule.md | New term page: Rule. |
| content/en/risk-catalog.md | New term page: Risk Catalog. |
| content/en/risk-assessment.md | New term page: Risk Assessment. |
| content/en/risk-appetite.md | New term page: Risk Appetite. |
| content/en/risk-acceptance.md | New term page: Risk Acceptance. |
| content/en/residual-risk.md | New term page: Residual Risk. |
| content/en/remediative-enforcement.md | New term page: Remediative Enforcement. |
| content/en/preventive-enforcement.md | New term page: Preventive Enforcement. |
| content/en/policy.md | New term page: Policy. |
| content/en/organization.md | New term page: Organization. |
| content/en/objective.md | New term page: Objective. |
| content/en/intent-evaluation.md | New term page: Intent Evaluation. |
| content/en/guideline.md | New term page: Guideline. |
| content/en/guidance.md | New term page: Guidance. |
| content/en/governance.md | New term page: Governance. |
| content/en/continuous-monitoring.md | New term page: Continuous Monitoring. |
| content/en/compliance.md | New term page: Compliance. |
| content/en/catalog.md | New term page: Catalog. |
| content/en/assessment.md | New term page: Assessment. |
| content/en/assessment-requirement.md | New term page: Assessment Requirement. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| title: Compliance | ||
| status: Completed | ||
| category: concept | ||
| tags: ["gemara","",""] |
| title: Continuous Monitoring | ||
| status: Completed | ||
| category: concept | ||
| tags: ["gemara","",""] |
| title: Risk Appetite | ||
| status: Completed | ||
| category: concept | ||
| tags: ["gemara","",""] |
| title: Risk Assessment | ||
| status: Completed | ||
| category: concept | ||
| tags: ["gemara","",""] |
| title: Risk Catalog | ||
| status: Completed | ||
| category: concept | ||
| tags: ["gemara","",""] |
| @@ -0,0 +1,10 @@ | |||
| --- | |||
| title: Rule | |||
| status: Feedback Appreciated | |||
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
|
|
||
| An intent evaluation is the process of analyzing and evaluating the stated intentions of a policy, mechanism, or subject to determine if it aligns with the expected security boundaries and overarching risk governance strategy. | ||
|
|
||
| Source: [ISACA Glossary - Evaluation](https://www.isaca.org/resources/glossary) No newline at end of file |
There was a problem hiding this comment.
Just cherry-picking one of the entries to this PR, "Intent Evaluation" is not an entry on the ISACA glossary.
I have not checked any of the other 20 entries.
There was a problem hiding this comment.
Great catch, Eddie. You're completely right. I went ahead and did a manual audit of the other terms against the NIST, ISACA, and SANS glossaries, and found a few more discrepancies.
Here is a breakdown of what I found and how I propose we fix it:
- Terms that need renaming to match the standard glossaries (and their current citations):
- Preventive Enforcement -> Preventive Control
- Remediative Enforcement -> Corrective Control
- Risk Catalog -> Risk Register
- Objective -> Security Objective
- Catalog -> Security Control Catalog
- Governance -> Governance, risk, and compliance (NIST)
- Terms with incorrect citations (that exist in other glossaries):
- Guideline & Risk Acceptance: Exists in ISACA (missing in SANS/NIST).
- Rule: Exists in NIST (missing in SANS).
- Proposal: I can update the markdown to cite the correct glossaries for these.
- Missing Terms:
- Intent Evaluation, Guidance, and Sensitive Activity don't seem to have entries in any of the three main glossaries.
How would you like to handle the missing terms? Should I drop them from this PR, find another authoritative source (like ISO/IEC 27000 or CNSSI 4009), or define them as project-specific without a citation?
Let me know your thoughts on this and the renaming, and I'll bundle all these fixes into a new commit!
There was a problem hiding this comment.
Thanks @PaarthPandey10, I'm curious about why the Gemara definitions have proven insufficient?
ICYMI: https://gemara.openssf.org/model/02-definitions
Your suggestions here are aligned well enough to deserve a cross-reference to inform readers of the similarities in the terms, but simply dropping the Gemara-originated term seems to defeat the purpose of this PR.
There was a problem hiding this comment.
Hey @eddie-knight, that makes perfect sense. I completely misunderstood the goal and was replacing the original text rather than bridging it. My mistake for trying to overwrite the Gemara ontology!
I really like the cross-reference idea. I plan to update the markdown files so the Gemara definition sits at the top as the primary text, followed by an ### Industry Cross-Reference section containing the NIST/ISACA definitions.
Before I push the new commit, I just want to make sure we are aligned on how to handle a few edge cases:
-
Terms with different industry names: For concepts where the standard uses a different term (e.g., Gemara's Risk Catalog vs. NIST's Risk Register), should I keep the file name and primary title as the Gemara term (risk-catalog.md) and simply note the alternate name in the cross-reference section?
-
Gemara-exclusive terms: For terms like Intent Evaluation or Sensitive Activity that don't have a direct equivalent in NIST/ISACA, should I just leave them as standalone Gemara definitions with no cross-reference section?
(Note: For the terms that just had incorrect citations, I'll go ahead and fix those links within the new cross-reference blocks).
Let me know if this approach works for you, and I'll get the PR updated!
There was a problem hiding this comment.
I'll let Eddie answer item 1 but my vote for 2 is to go ahead and leave them as standalone Gemara definitions.
There was a problem hiding this comment.
Yep, what Jeff said makes sense for 2. And for 1 I agree with you, if we're picking the primary filename/title/entry then we should stick use the Gemara term and then reference out to other comparative terms as needed
There was a problem hiding this comment.
Awesome, thanks for confirming @GeauxJD and @eddie-knight!
I've just pushed a new commit that restructures all 21 files based on our discussion. Here is a quick summary of how it is laid out now:
-
Preserved Gemara Ontology: The primary file names, titles, and top-level definitions across all files now strictly use the original Gemara terminology.
-
Industry Cross-References: For terms with NIST or ISACA equivalents, I appended an ### Industry Cross-Reference section directly below the Gemara definition. This includes the exact industry definition, any alternate terminology (e.g., mapping Gemara's Risk Catalog to ISACA's Risk Register), and the correct source citation.
-
Gemara-Exclusive Terms: As Jeff suggested, terms without direct external equivalents (like Intent Evaluation, Guidance, and Sensitive Activity) were left purely as standalone Gemara definitions without any external cross-referencing.
This should give readers the standard industry alignment while keeping the Gemara model front and center. Let me know how this looks to you guys!
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
There was a problem hiding this comment.
Looks great, thanks for this Parth!
Suggestion from @jpower432 today: after each definition, could we add Source: Gemara with a link to the whitepaper or the website?
Signed-off-by: PaarthPandey10 <paarthdxb@gmail.com>
Describe your changes
This PR migrates the first batch of definitions from the Gemara lexicon to the OpenSSF Glossary. These are the terms that received no review objections during the initial review of PR #88.
wordlist.txtto whitelist unique technical jargon for CI spellcheck compliance.Related issue number or link
Relates to #83
Checklist before opening this PR (put
xin the checkboxes)