C++: Add more documentation about dataflow through indirections #14524

MathiasVP · 2023-10-17T08:25:48Z

This PR adds a new article (linked from https://codeql.github.com/docs/codeql-language-guides/codeql-for-cpp/) explaining how we would tackle a few situations that involve tainting a pointer or tainting its indirection.

We know from past experience that this has been something Microsoft has needed some explanation of, and this document should hopefully answer some of the common questions we've gotten (with the expectation that other people will have similar questions).

cc @felicitymay

geoffw0

Just read this through. Looks fantastic and very valuable to advanced users! I do have a fair number of minor corrections and some suggestions that I think may improve readability. Feel free to accept / reject / change / discuss my suggestions as you see fit.

I have not checked all the links work.

docs/codeql/codeql-language-guides/advanced-dataflow-scenarios-cpp.rst

…-cpp.rst Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>

…cess' section.

felicitymay · 2023-10-17T14:46:50Z

I'm going to hold off on starting the writer review until you let me know that the technical review is complete.

MathiasVP · 2023-10-17T14:47:55Z

I'm going to hold off on starting the writer review until you let me know that the technical review is complete.

Thanks. Sorry about the premature ping. I'll make sure to ping you once I've worked through Geoffrey's comments.

…-cpp.rst Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>

MathiasVP · 2023-10-17T15:08:14Z

@geoffw0 thanks for all the great feedback! I think I've incorporated all the changes that I wanted to incorporate 😅. I think the only one I left out was #14524 (comment) because I do think it serves a purpose to show that "standard dataflow" works well even for complex cases such as this.

geoffw0 · 2023-10-17T15:23:05Z

@MathiasVP has addressed all my comments, I'm happy.

felicitymay · 2023-10-17T15:45:33Z

I'll take a look tomorrow morning 👍🏻

felicitymay

Many thanks for taking the time to write this detailed article. It looks as if the examples of different ways to track pointers and indirections will be really useful in helping query writers understand their options. 💖

I've added a lot of small text suggestions and a few other thoughts on how this could be clearer. As always, please take care to ensure that the suggested changes don't change the meaning, and remember that I'm not in the target audience for this article so feel free to reject suggestions 🙂

docs/codeql/codeql-language-guides/advanced-dataflow-scenarios-cpp.rst

felicitymay · 2023-10-18T11:52:49Z

docs/codeql/codeql-language-guides/advanced-dataflow-scenarios-cpp.rst

+    free(u);
+  }
+
+Since data is no longer a pointer our ``isAdditionalFlowStep`` doesn't make any sense because it specifies flow to the indirection of the field (and an integer does not have any indirections). So there is no choice about whether to taint the value of the field or its indirection: it has to be the value. However, since we pass the address of ``data`` to ``use_pointer`` the tainted data is what is pointed to by the argument of ``use_pointer`` (since the data pointed to by ``&data`` is exactly ``data``). So to handle this case we need a mix of the two situations above:


I find this difficult to follow. Is it possible to simplify it?

Indeed this is technically a complex paragraph. I've tried to clear up the explanation in a36d432.

docs/codeql/codeql-language-guides/advanced-dataflow-scenarios-cpp.rst

docs/codeql/codeql-language-guides/codeql-for-cpp.rst

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Co-authored-by: Felicity Chapman <felicitymay@github.com>

…-cpp.rst

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

…ile.

…-cpp.rst

MathiasVP · 2023-10-18T13:39:54Z

@felicitymay thank you for all the suggestions. They certainly made the article a lot nicer to read! I believe I've fixed all your comments now 🤞

felicitymay · 2023-10-18T14:05:02Z

I believe I've fixed all your comments now 🤞

Many thanks for working through all the comments 💖

Sadly I have meetings the rest of the day, but I will take a last look tomorrow morning.

felicitymay

Many thanks for all the updates. I found a couple of very small nits, but otherwise this looks ready to merge.

I particularly like the way you've formatted the C/C++ examples.

docs/codeql/codeql-language-guides/advanced-dataflow-scenarios-cpp.rst

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

felicitymay · 2023-10-19T09:03:08Z

@MathiasVP - we're just about to start the update process for the CodeQL docs site for the release of the CLI. If you'd like this to be published sooner, you could retarget this against the release candidate branch. Otherwise, this is likely to be published in a couple of weeks.

MathiasVP · 2023-10-19T09:11:09Z

@MathiasVP - we're just about to start the update process for the CodeQL docs site for the release of the CLI. If you'd like this to be published sooner, you could retarget this against the release candidate branch. Otherwise, this is likely to be published in a couple of weeks.

Thanks for the heads up. There's no rush to get this in, so I think we'll just wait for the next release 🙂.

github-actions bot added the documentation label Oct 17, 2023

C++: Add more documentation about dataflow through indirections.

75a8f01

MathiasVP force-pushed the add-more-dataflow-documentation branch from ab880de to 75a8f01 Compare October 17, 2023 08:53

MathiasVP added the ready-for-doc-review This PR requires and is ready for review from the GitHub docs team. label Oct 17, 2023

geoffw0 reviewed Oct 17, 2023

View reviewed changes

MathiasVP and others added 6 commits October 17, 2023 15:50

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

fa3053f

…-cpp.rst Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

e264bdd

…-cpp.rst Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>

C++: Simplify introductory text and code.

3de32e8

C++: Reorganize the setup in the 'Flow from a qualifier to a field ac…

d6ccd63

…cess' section.

C++: Replace 'use_data' with 'read_data'.

c5307be

C++: Fix phinx syntax.

2fcf0ab

MathiasVP and others added 5 commits October 17, 2023 15:57

C++: Add a small note about performance.

0a71705

C++: Delete 'we assume'.

d390b62

C++: Make an explanation of 'allowImplicitRead' slightly more explicit.

c4075b3

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

17ee7c2

…-cpp.rst Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

9a6fc96

…-cpp.rst Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>

C++: Make sphinx happy.

c8e8ac0

felicitymay reviewed Oct 18, 2023

View reviewed changes

MathiasVP and others added 7 commits October 18, 2023 14:03

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

d219431

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

e6ae3ff

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

02e3d27

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

51cf400

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

16fbffe

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

f3dd2eb

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

56a1a7c

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

MathiasVP and others added 19 commits October 18, 2023 14:06

Update docs/codeql/codeql-language-guides/codeql-for-cpp.rst

b71248f

Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

59b26c0

…-cpp.rst

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

9ad461d

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

efe7153

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

9a91145

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

d4cbb8c

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

0d36d91

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

8812567

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

3b6c43c

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

ff3d4b8

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

C++: Move the note in the beginning of the document into a reusable f…

9d2e21e

…ile.

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

342f4f8

…-cpp.rst

C++: Convert a paragraph to a numbered list.

1b1a78b

C++: Convert another paragraph to a numbered list.

f6b1d66

C++: Stick to the pointer vs. indirection terminology.

44e214b

C++: Fix typo.

308d027

C++: Use named code blocks.

c04546d

C++: Simplify a paragraph and use line numbers in CPP code.

a36d432

C++: Make sphinx happy.

7f97492

felicitymay previously approved these changes Oct 19, 2023

View reviewed changes

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

35702a9

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

MathiasVP dismissed felicitymay’s stale review via 35702a9 October 19, 2023 09:00

MathiasVP and others added 2 commits October 19, 2023 11:00

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

b5cbd90

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

Update docs/codeql/codeql-language-guides/advanced-dataflow-scenarios…

4feda50

…-cpp.rst Co-authored-by: Felicity Chapman <felicitymay@github.com>

felicitymay approved these changes Oct 19, 2023

View reviewed changes

MathiasVP merged commit 0bfa53c into github:main Oct 19, 2023
7 checks passed

C++: Add more documentation about dataflow through indirections #14524

C++: Add more documentation about dataflow through indirections #14524

MathiasVP commented Oct 17, 2023

geoffw0 left a comment

felicitymay commented Oct 17, 2023

MathiasVP commented Oct 17, 2023

MathiasVP commented Oct 17, 2023

geoffw0 commented Oct 17, 2023

felicitymay commented Oct 17, 2023

felicitymay left a comment

felicitymay Oct 18, 2023

MathiasVP Oct 18, 2023

MathiasVP commented Oct 18, 2023

felicitymay commented Oct 18, 2023

felicitymay left a comment

felicitymay commented Oct 19, 2023

MathiasVP commented Oct 19, 2023

C++: Add more documentation about dataflow through indirections #14524

C++: Add more documentation about dataflow through indirections #14524

Conversation

MathiasVP commented Oct 17, 2023

geoffw0 left a comment

Choose a reason for hiding this comment

felicitymay commented Oct 17, 2023

MathiasVP commented Oct 17, 2023

MathiasVP commented Oct 17, 2023

geoffw0 commented Oct 17, 2023

felicitymay commented Oct 17, 2023

felicitymay left a comment

Choose a reason for hiding this comment

felicitymay Oct 18, 2023

Choose a reason for hiding this comment

MathiasVP Oct 18, 2023

Choose a reason for hiding this comment

MathiasVP commented Oct 18, 2023

felicitymay commented Oct 18, 2023

felicitymay left a comment

Choose a reason for hiding this comment

felicitymay commented Oct 19, 2023

MathiasVP commented Oct 19, 2023