Document threat models

[saritai]

This pull request addresses https://github.com/github/docs-content/issues/12431.

Release issue: https://github.com/github/releases/issues/3545

Reviewers: I'd like to know if the information I included is accurate, is enough detail, and is not missing anything. I put it in a new separate section of the article, since these extensible predicates are part of the separate threat-modelsshared library pack. I'll clean up some of the language/structure later but just wanted to make sure I am on the right track.

[aeisenberg]

Thanks for writing this up.

I think it's important to link the threat model kind to the 8th value in the sourceModel and mention that if environment is enabled, then all source models of the environment kind will be included in the analysis. Otherwise, they will be excluded.

In the example you have:

       - [local, true, 0]
       - [environment, false, 1]

All local threat models will be enabled, except for environment variables threat sources, which are disabled. I think the fact that there is a hierarchy of threat models is important to get across as well here.

[jf205]

Thanks for opening this PR @saritai. The internal doc you got the information from contains quite low-level detail so I've tried to make the new section easier for external users to understand. I pushed the changes directly as it was easier than making suggestions on the PR but please feel free to edit my additions as much as you like ❤️

[jf205]

Please can you add links to the information about using threat models with the CLI and in code scanning?

[saritai]

I've added links based on the new sections in the docs-internal PR. However, I am not sure if the names of those sections are set in stone, so will want to wait till Monday to confirm before we merge this PR.

Also good to note that right now, those links just lead to the top level of the article since the sections don't exist. But doesn't seem to lead to any 404s (since the articles themselves already exist, the sections just don't) so should be alright to keep them in there (and these docs will be published after the docs-internal PR).

[jf205]

Thanks for writing this up.

I think it's important to link the threat model kind to the 8th value in the sourceModel and mention that if environment is enabled, then all source models of the environment kind will be included in the analysis. Otherwise, they will be excluded.

In the example you have:

       - [local, true, 0]
       - [environment, false, 1]

All local threat models will be enabled, except for environment variables threat sources, which are disabled. I think the fact that there is a hierarchy of threat models is important to get across as well here.

@aeisenberg do you think we need to talk to this level of detail? It seems more appropriate for our internal authors. I think we can talk about what threat models are in relation to the sourceModel predicate and then describe (or link to information) about how they are used to customize analyses with the CLI and in code scanning. Mentioning their implementation with data extensions seems out of scope for this release.

[aeisenberg]

This looks great to me.

Currently, this applies to java-kotlin only, but threat models are being rolled out to the other languages as well. Each language should use the same threat kinds. Is the plan to document each language individually or merge the parts of the documentation that are shared?

Either way, I think what you have here is fine for now.

[saritai]

@aeisenberg Thanks for the review! And great point about this coming to other languages. We could definitely make part of this section a reusable and then use that for the other languages, but I suppose we can just do that once the next language comes up 👍

I'll just wait till Monday to merge this PR because I want to make sure the links I have to the CodeQL CLI and code scanning docs are correct (not sure if they will change).

[subatoi]

Only one tiny typo that seems to have already been there: happy to look again and approve after SMEs have taken a last look, if needed!

Thanks again for writing this up, Sarita! ✨