Skip to content

Updates to the Java and VS Code docs #14207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 28 commits into from
Sep 18, 2023
Merged

Conversation

felicitymay
Copy link
Contributor

@felicitymay felicitymay commented Sep 13, 2023

This pull request is ready for review. It's been a little rushed so may have more typos than I'd like 😞

Main changes:

  1. Content about data extensions and their format moved from Customizing Library Models for Java into a new reference article, currently called: "Data extensions to model your Java/Kotlin dependencies".
  2. Data about extensible predicates consolidated in "Extensible predicates and their interaction with data extensions"
  3. New article about how to create models using the VS Code extension.

I'd like to follow up with a tutorial demonstrating the method for modeling a few API calls, but this will need help from an expert to find a suitable example.

@felicitymay felicitymay marked this pull request as ready for review September 14, 2023 20:51
@felicitymay felicitymay requested a review from a team as a code owner September 14, 2023 20:51
@felicitymay felicitymay changed the title [DRAFT] Updates to the Java and VS Code docs Updates to the Java and VS Code docs Sep 14, 2023
@felicitymay felicitymay added the ready-for-doc-review This PR requires and is ready for review from the GitHub docs team. label Sep 14, 2023
@felicitymay felicitymay requested a review from jf205 September 14, 2023 22:12
@felicitymay
Copy link
Contributor Author

@michaelnebel - here is the whole PR that we were discussing.

subatoi
subatoi previously approved these changes Sep 15, 2023
Copy link
Contributor

@subatoi subatoi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good—only minor comments, some of which are probably not relevant. Don't feel the need to respond individually, just resolve as you see fit. Happy to take another look after it's been through technical review 👍

Copy link
Contributor

@robertbrignull robertbrignull left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've only read through docs/codeql/codeql-for-visual-studio-code/using-the-codeql-model-editor.rst, because that's the part I'm most familiar with. I spotted a few typos, but the article as a whole looks good to me and all of the information is correct.

@felicitymay
Copy link
Contributor Author

@subatoi and @robertbrignull - thank you so much for finding time to review this so soon after I posted it. Clearly I should have waited until I took a look this morning, but thanks for fixing all my typos and for the other suggestions 💖

Robert - thank you particularly for checking the technical accuracy of the VS Code extension information. That's great to hear 🎉

All suggestions applied. I suspect that the larger question is over whether or not the content is split and organized appropriately, and I've no doubt James will have some thoughts on that.

@felicitymay
Copy link
Contributor Author

felicitymay commented Sep 15, 2023

It looks as if I probably need to retarget these changes against a GHES branch, but I'll leave worrying about that for now.

Copy link
Contributor

@jf205 jf205 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is looking pretty good already @felicitymay. Thank you! ❤️
I've added a few comments so far which i think can be addressed any time. I'm going to take a second look and will probably end up adding some more.

Modeling the calls your codebase makes to external APIs
-------------------------------------------------------

You typically use this method when you are looking at a specific codebase where you want to improve the precision of CodeQL results. This is usually when the codebase uses frameworks or libraries that are not supported by CodeQL but they are not used by other teams in your organization.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but they are not used by other teams in your organization. -> and if the sourcecode of the framework or library is not included in the analysis.
One could imagine a non-monolith architecture where a project has dependencies to internal packages, but where the source code of these are not included in the analysis.


This article contains reference material about how data extensions interact with standard queries and the syntax used to define extensions.

If you want to create your own data extensions, you should use the CodeQL model editor in the CodeQL extension for Visual Studio Code. The model editor automatically guides you through the process of defining models, displaying the properties you need to define and the options available. You can save the resulting models as data extensions and use them without worrying about the syntax.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Data extensions are more general than the specific extensible predicates used for MaD modelling. We could imagine other uses cases than MaD for data extensions - we expect to use extensible predicates for threat modelling as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for flagging this. I'll leave @jf205 to decide whether we should generalize this now, or in the future when document threat modeling ✨

@michaelnebel
Copy link
Contributor

@michaelnebel - here is the whole PR that we were discussing.

Great - thank you 👍 I see that you incorporated the changes from #13864 which I will go ahead and close 😄

subatoi
subatoi previously approved these changes Sep 16, 2023
Copy link
Contributor

@subatoi subatoi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just had some further tiny non-blocking comments on second content review, but this is looking like an awesome piece of work 👍

@felicitymay
Copy link
Contributor Author

Many thanks for the most recent review comments @jf205. I've merged those, and will make the changes locally to fix he length of the header-underlining and rename the article (which I omitted in my earlier update).

@felicitymay
Copy link
Contributor Author

Apologies for the force push and noise, but I needed to rebase this on the rc/3.11 branch.

@felicitymay
Copy link
Contributor Author

It would be great if we could merge this before @alexet creates the next release candidate branch for the CodeQL CLI release, but I need another approval.

@felicitymay
Copy link
Contributor Author

Thanks for the approval ✨

The tests seem to be running slowly, but hopefully will pass eventually 🤞🏻

@felicitymay felicitymay added the no-change-note-required This PR does not need a change note label Sep 18, 2023
@felicitymay felicitymay merged commit 31b0c42 into rc/3.11 Sep 18, 2023
@felicitymay felicitymay deleted the felicitymay-11595-VS-code-docs branch September 18, 2023 17:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Java no-change-note-required This PR does not need a change note ready-for-doc-review This PR requires and is ready for review from the GitHub docs team.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants