feat: adds gemara lexicon terms to glossary

[hbraswelrh]

Describe your changes

This PR decouples the Gemara Lexicon from the Gemara project. The terms are separated commit by commit. The three latest commits are refactoring and updates to the wordlist.txt as mentioned in the style-guide.md. The Gemara Official Publication is cited as the Source for the terms (cc: @eddie-knight).

The capabilities.md was the only existing term that was updated.

Related issue number or link (ex: resolves #issue-number)

• Resolves Issue [New term] GlossaryTerms from Gemara Lexicon of Terms #83
• Closes PR WIP: add gemara terms #82

Checklist before opening this PR (put x in the checkboxes)

• This PR does not contain plagiarism
  • don’t copy other people’s work unless you are quoting and contributing it to them.
• I have signed off on all commits
  • signing off (ex: git commit -s) is to affirm that commits comply DCO. If you are working locally, you could add an alias to your gitconfig by running git config --global alias.ci "commit -s".

[GeauxJD]

@hbraswelrh the spellcheck and links checks are failing. can you check the spellcheck report and add the necessary words, like "gemara", to the wordlist.txt?

for the links, if you are cross-linking words i think you need to point to the urls without the .md on the end.

[GeauxJD]

@hbraswelrh there are a few more words showing up in the spellcheck report that will need to be added.

also my apologies but I gave you an incorrect suggestion on how to fix the cross-links to other terms. it looks like leading and trailing slashes to the word will satisfy the link checker, based upon this example in CNCF glossary:

https://github.com/cncf/glossary/blob/main/content/en/abstraction.md?plain=1 (see the link for services)

[hbraswelrh]

@hbraswelrh there are a few more words showing up in the spellcheck report that will need to be added.

also my apologies but I gave you an incorrect suggestion on how to fix the cross-links to other terms. it looks like leading and trailing slashes to the word will satisfy the link checker, based upon this example in CNCF glossary:

https://github.com/cncf/glossary/blob/main/content/en/abstraction.md?plain=1 (see the link for services)

Hi @GeauxJD Thank you so much for the suggestion. I apologize for the noisy errors. I will make some updates based on the CNCF glossary link you shared.

[david-a-wheeler]

Suggested change

	An audit is a formal, opinionated review of an organization's [policy](policy) and posture, conducted at a specific point in time to verify that established requirements are met.
	An audit is a formal review of an organization's [policy](policy) and posture, conducted at a specific point in time to verify that established requirements are met.

"Opinionated" implies "incorrect" and "subject to the whims of the auditor, not necessarily based in reality". I'm sure you don't mean that.

[david-a-wheeler]

Suggested change

	A behavior evaluation is an opinionated observation of actions that are simulated or that occur in real use.
	A behavior evaluation is an observation of actions that are simulated or that occur in real use.

Again, I object to "opinionated". Also, I would expect an "evaluation" to do more than perform "observation", shouldn't it also "judge their effectiveness"?

[david-a-wheeler]

Suggested change

	b. Linux kernel uses capabilities to compartmentalize the UNIX root privilege into a set of non-overlapping sub privileges (called capabilities) that can be individually assigned where higher granularity than root/non-root is suitable.
	b. In some systems, such as the Linux kernel, a capability is a non-overlapping subbset of UNIX root privilege that can be individually assigned where higher granularity than root/non-root is desired.
	c. In some systems, such as seL4, a capability is a communicable, unforgeable token of authority.

You need to define the term. Also, capability-based security is a thing, and we shouldn't ignore a standard definition of the term.

[david-a-wheeler]

Suggested change

	A control can mean: (1) an organization's ability to fully assert desired state on a system, resource, or state; (2) a mechanism such as a safeguard or countermeasure that asserts desired state; or (3) prose describing the [objective](objective) and [assessment requirement](assessment-requirement)s associated with a desired state.
	A control can mean: (1) an organization's ability to fully assert desired state on a system, resource, or state; (2) a mechanism such as a safeguard or countermeasure that enforces or asserts a desired state; or (3) prose describing the [objective](objective) and [assessment requirement](assessment-requirement)s associated with a desired state.

A control in sense (2) typically enforces something, not just "asserts" it.

[david-a-wheeler]

Suggested change

	It supports [preventive enforcement](preventive-enforcement) and [remediative enforcement](remediative-enforcement) and helps close gaps in [compliance](compliance).
	This may include changes to prevent future issues, remediating past results, and penalties for non-compliance.
	It supports [preventive enforcement](preventive-enforcement) and [remediative enforcement](remediative-enforcement) and helps close gaps in [compliance](compliance).

[david-a-wheeler]

Suggested change

	An evaluation finding is the evidence and opinionated result of an [assessment](assessment).
	An evaluation finding is the evidence and adjudicated result of an [assessment](assessment).

"Opionated" means "assertively dogmatic in expressing opinions", and typically implies "a statement unsupported by or even contrary to the facts of the situation". That isn't what you mean.

[david-a-wheeler]

Suggested change

	Raw data without structure or [opinion](opinion) is hard to act on.
	Raw data without structure or [judgment](judgment) is hard to act on.

Don't use the word "opinion", that's a terrible word for what you intend. Try another one. Here I propose "judgment".

[david-a-wheeler]

Find another word than "opinion". You mean something that's supported by facts, like a judgment - not an opinion.

[david-a-wheeler]

Suggested change

	Source: [Gemara: A Governance, Risk, and Compliance Engineering Model for Automated Risk Assessment](https://openssf.org/resources/gemara-a-governance-risk-and-compliance-engineering-model-for-automated-risk-assessment/)
	Source: [Gemara: A Governance, Risk, and Compliance Engineering Model for Automated Risk Assessment](https://openssf.org/resources/gemara-a-governance-risk-and-compliance-engineering-model-for-automated-risk-assessment/)
	[NIST Cyber Security Resource Center Glosssary, GRC](https://csrc.nist.gov/glossary/term/grc)

GRC is a whole industry. I don't mind citing Gemara, but we should cite something more authoritative as well.

[david-a-wheeler]

I think this is not a good word for your purpose. I would recommend a different word, like "judgment".

At the least avoid "opionated" which implies forming a judgment regardless of, and possibly contrary to, the facts.

[jpower432]

In this context, opinion is used in the technical sense to mean the formal expression of a conclusion (i.e., audit opinion). To me, judgment describes the action or process of forming that conclusion, whereas the opinion is the final outcome. However, I completely agree that using the word opinion in a standalone glossary definition and sprinkled through the other definitions without the full context of the whitepaper is problematic and can be easily misread as a hunch.

[david-a-wheeler]

It doesn't have to be judgment; Thesaurus.com has some possible synonyms for opinion including: assessment and conclusion.

I'm leaving out many other synonyms like speculation, feeling, impression, notion, and viewpoint (the fact that they are synonyms hopefully shows why this word is concerning).

[eddie-knight]

We can omit this from the glossary if needed, but we already shipped this in the Gemara whitepaper.

Also, I'm quite partial to this definition for all the reasons that you listed as protests 😆 An evaluation or audit can be correct or otherwise, but the entity performing the audit/evaluation is obligated to have some opinion. Better opinions means fewer false positives and false negatives.

[david-a-wheeler]

Suggested change

	Risk mitigation is the process of defining and taking actions to prevent [threat](threat)s or reduce their impact on [organization](organization) objectives.
	Risk mitigation is the process of defining and taking actions to prevent [threat](threat)s, or reduce their likelihood and/or impact on [organization](organization) objectives.

Impact is only 1 part of risk; likelihood the other.

[david-a-wheeler]

Suggested change

	Risk is the potential for loss or damage when a [threat](threat) is actualized, determined by calculating the impact of an event on an [organization](organization) and the likelihood of its occurrence.
	Risk is the potential for loss or damage, such as when a [threat](threat) is actualized, determined by the impact of an event on an [organization](organization) and the likelihood of its occurrence.

"Risk" isn't limited to security - use that only as an example. Risks aren't always formally calculated... they're risks even when they aren't.

[david-a-wheeler]

This is overly complicated.

Look at these for clearer definitions:
https://csrc.nist.gov/glossary/term/threat

Somewhere should contrast with "threat actor" and/or "attacker".

[david-a-wheeler]

The NIST definition is, "Any circumstance or event with the potential to adversely impact organizational operations (including mission, functions, image, or reputation), organizational assets, or individuals through an information system via unauthorized access, destruction, disclosure, modification of information, and/or denial of service."

I guess you really want to include "vector" and "capability", but at least don't lead with these unusual terms. Something like this:

Suggested change

	A threat is a circumstance or event where the concepts of a [vector](vector) are applied to a [capability](capabilities) in a specific context, resulting in the potential for negative impact.
	A threat is a circumstance or event with the potential for an adverse impact (e.g., on organizational operations, assets or individuals) due to a [vector](vector) applied to a [capability](capabilities) in a specific context.

[jpower432]

@david-a-wheeler @hbraswelrh The terms here are directly from the Gemara paper used specifically to help the reader understand the contents. I think what we are finding here is that some of these terms need the context from other terms to fully make sense which I would expect would be problematic for the glossary definition (assuming the definitions here should be self-contained). Perhaps it would be better to identify the terms that are most useful to add and create smaller PRs from there. WDYT?

[david-a-wheeler]

Why only unintentional? Neglect could provide an opportunity for a malicious actor.

[eddie-knight]

Suggested change

	A vector is (1) an opportunity for an attacker to exploit a [vulnerability](vulnerability) in a system, or (2) a path by which neglect could result in unintentional negative outcomes.
	A vector is (1) an opportunity for an attacker to exploit a [vulnerability](vulnerability) in a system, or (2) a path by which neglect could result in negative outcomes.

[david-a-wheeler]

Suggested change

	A vulnerability is (1) a weakness in a system inherent in or associated with a [capability](capabilities) that can be exploited when used in unintended ways, or (2) a lack of [control](control) or gap in defense, introduced intentionally or unintentionally, which can be leveraged to cause harm.
	A vulnerability is (1) a weakness in a system inherent in or associated with a [capability](capabilities) that can be exploited, or (2) a lack of [control](control) or gap in defense, introduced intentionally or unintentionally, which can be leveraged to cause harm.

It might be intentionally inserted, you can't know the mind of the original developer.

[david-a-wheeler]

@hbraswelrh - thanks so much, I wrote a bunch of specific comments that I hope will help.

I'm concerned about the word "opinion" and especially "opinionated" in this context, see my comments above. You might also want to look at other sources; I find NIST helpful:
https://csrc.nist.gov/glossary/

[david-a-wheeler]

I think what we are finding here is that some of these terms need the context from other terms to fully make sense which I would expect would be problematic for the glossary definition (assuming the definitions here should be self-contained). Perhaps it would be better to identify the terms that are most useful to add and create smaller PRs from there. WDYT?

Dropping some terms might make sense, but in at least some cases, the definition just needs refinement. In the long term that is a good thing - a definition that's clear and stands on its own will be better. Good definitions are hard. I suggest working to make the definitions better first, and drop the ones where that's too hard or the cost exceeds the benefit.

[hbraswelrh]

@hbraswelrh - thanks so much, I wrote a bunch of specific comments that I hope will help.

I'm concerned about the word "opinion" and especially "opinionated" in this context, see my comments above. You might also want to look at other sources; I find NIST helpful: https://csrc.nist.gov/glossary/

Hi @david-a-wheeler, thank you very much for sharing the thorough feedback on this PR. I apologize for the delayed response. The terms were extracted directly from the Gemara Whitepaper so I will discuss this PR with the maintainers in the upcoming Gemara Community Meeting to ensure updates are made accordingly.