C#: Models as Data Documentation #15563
Conversation
egregius313
force-pushed
the
egregius313/csharp/docs/mad-docs
branch
from
9821ffb
to
4d31893
Compare
egregius313
force-pushed
the
egregius313/csharp/docs/mad-docs
branch
from
4d31893
to
4e75726
Compare
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
| About data extensions | ||
| --------------------- | ||
|
|
||
| You can customize analysis by defining models (summaries, sinks, and sources) of your code's C#/.NET dependencies in data extension files. Each model defines the behavior of one or more elements of your library or framework, such as methods, properties, and callables. When you run dataflow analysis, these models expand the potential sources and sinks tracked by dataflow analysis and improve the precision of results. |
There was a problem hiding this comment.
customize analysis -> customize analyses?
There was a problem hiding this comment.
And dataflow analysis -> dataflow analyses.
There was a problem hiding this comment.
Not sure which is better, but that wording is taken from the Java customizing-library-models docs.
| - ``sourceModel(namespace, type, subtypes, name, signature, ext, output, kind, provenance)``. This is used to model sources of potentially tainted data. | ||
| - ``sinkModel(namespace, type, subtypes, name, signature, ext, input, kind, provenance)``. This is used to model sinks where tainted data maybe used in a way that makes the code vulnerable. | ||
| - ``summaryModel(namespace, type, subtypes, name, signature, ext, input, output, kind, provenance)``. This is used to model flow through elements. | ||
| - ``neutralModel(namespace, type, name, signature, kind, provenance)``. This is similar to a summary model but used to model the flow of values that have only a minor impact on the dataflow analysis. |
There was a problem hiding this comment.
have only a minor impact -> have no impact?
There was a problem hiding this comment.
If this should be changed to no impact I am totally fine doing so. This is taken from how Java's MaD docs describes it, so if it needs to be changed it might make sense to change it in both.
There was a problem hiding this comment.
We need to change this statement; Also for java.
After #15246 was merged, manual neutral summary models have impact for both C# and Java as they "override" generated summaries (that is, if a manual neutral exist for a callable we ignore any generated summary for it).
That is, for
C#: Manual neutral models can be used over to override generated summary models, such that the generated summary models will be ignored; other than that they have no effect.
Java: Manul neutrals models overrides generated summary models, such that the generated summary models will be ignored; other than that they have a sligt impact on the dataflow dispatch logic, which is out of scope for this documentation.
| } | ||
| } | ||
| We need to add a tuple to the ``sinkModel``\(namespace, type, subtypes, name, signature, ext, input, kind, provenance) extensible predicate by updating a data extension file. |
There was a problem hiding this comment.
I'm not familiar with .rst syntax, but the above looks wrong?
There was a problem hiding this comment.
I think the purpose of that is so that only the word sinkModel is rendered as code and be highlighted. But if we think that it's fine to highlight the entirety of sinkModel(namespace, ..., I can change it over.
cf The Java MaD docs:
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
| Since we are adding flow through a method, we need to add tuples to the ``summaryModel`` extensible predicate. | ||
| Each tuple defines flow from one argument to the return value. | ||
| The first row defines flow from the first argument (``s1`` in the example) to the return value (``t`` in the example) and the second row defines flow from the second argument (``s2`` in the example) to the return value (``t`` in the example). |
There was a problem hiding this comment.
The wording probably needs to be changed, as the two rows were collapsed into one.
You could consider to write the example using two rows and then state that the rows can be collapsed into a single row using the more compact syntax Argument[0,1].
docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
@egregius313 : Really good examples!
It would be great, if we could also make something similar to extensible-predicates.rst which is currently java specific (and for some reason not linked from the java documentation).
Co-authored-by: Michael Nebel <michaelnebel@github.com>
Introduces Models-as-Data documentation for C#
Later follow-up will be to add the threat modeling documentation.