Rust: update docs #19280
Rust: update docs #19280
Conversation
redsun82
changed the title
There was a problem hiding this comment.
A few more libraries we model (partial support, but then I don't think we can claim to fully model any libraries). Sorry I probably missed a few of these in the list I sent you before.
We also have models for the standard io library coming in #19304 , I should update that PR once this is merged or vice-versa.
Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>
Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
redsun82
changed the title
There was a problem hiding this comment.
The two docs + other changes look great to me!
Some minor suggestions below.
"CodeQL library for Rust" doesn't go into a lot of detail, I think that's OK at this stage, it would be nice to have more example code in future.
I haven't checked the links, references to notes, and generally that everything fits together correctly - we really need a full preview for that and/or to be ready to correct any problems quickly after this goes live.
You should probably get a review from the docs team next?
|
|
||
| - The class ``RemoteFlowSource`` represents data flow from remote network inputs and from other applications. | ||
| - The class ``LocalFlowSource`` represents data flow from local user input. | ||
| - The class ``FlowSource`` includes both of the above. |
There was a problem hiding this comment.
I think I'd prefer if we point people to Concepts.qll and the classes there. I'd prefer people use that interface, and it has a wider variety of pre-defined sources.
| f.getParam(index).getPat().(IdentPat).getName().getText() = "password" | ||
| ) | ||
| } | ||
| } |
There was a problem hiding this comment.
Indending needs fixing above.
| exists(Function f, CallExpr call, int index | | ||
| call.getArg(index) = node.asExpr().getExpr() and | ||
| call.getStaticTarget() = f and | ||
| f.getParam(index).getPat().(IdentPat).getName().getText() = "password" |
There was a problem hiding this comment.
We should strongly consider adding helper predicates getParamName and getArgName to make code like this a bit cleaner?
| analyzing-data-flow-in-rust | ||
|
|
||
| - :doc:`CodeQL library for Rust <codeql-library-for-rust>`: When you're analyzing Rust code, you can make use of the large collection of classes in the CodeQL library for Rust. | ||
| - :doc:`Analyzing data flow in Ruby <analyzing-data-flow-in-rust>`: You can use CodeQL to track the flow of data through a Rust program to places where the data is used. |
There was a problem hiding this comment.
| - :doc:`Analyzing data flow in Ruby <analyzing-data-flow-in-rust>`: You can use CodeQL to track the flow of data through a Rust program to places where the data is used. | |
| - :doc:`Analyzing data flow in Rust <analyzing-data-flow-in-rust>`: You can use CodeQL to track the flow of data through a Rust program to places where the data is used. |
| module `rust.qll <https://github.com/github/codeql/blob/main/rust/ql/lib/rust.qll>`__ imports most other standard library modules, so you can include the complete | ||
| library by beginning your query with: |
There was a problem hiding this comment.
If it's "most" other standard library modules, it's not really "complete".
| module `rust.qll <https://github.com/github/codeql/blob/main/rust/ql/lib/rust.qll>`__ imports most other standard library modules, so you can include the complete | |
| library by beginning your query with: | |
| module `rust.qll <https://github.com/github/codeql/blob/main/rust/ql/lib/rust.qll>`__ imports most other standard library modules, you can include them by beginning your query with: |
| The CodeQL libraries model various aspects of Rust code. The above import includes the abstract syntax tree (AST) library, which is used for locating program elements, | ||
| to match syntactic elements in the source code. This can be used for example to find values, patterns and structures. |
There was a problem hiding this comment.
I'd drop this comma.
| The CodeQL libraries model various aspects of Rust code. The above import includes the abstract syntax tree (AST) library, which is used for locating program elements, | |
| to match syntactic elements in the source code. This can be used for example to find values, patterns and structures. | |
| The CodeQL libraries model various aspects of Rust code. The above import includes the abstract syntax tree (AST) library, which is used for locating program elements | |
| to match syntactic elements in the source code. This can be used for example to find values, patterns and structures. |
| Data flow is particularly useful for security queries, where untrusted data flows to vulnerable parts of the program | ||
| to exploit it. Related to data flow, is the taint-tracking library, which finds how data can *influence* other values |
There was a problem hiding this comment.
I'm not clear what "it" is, and I think these few words are superfluous anyway.
| Data flow is particularly useful for security queries, where untrusted data flows to vulnerable parts of the program | |
| to exploit it. Related to data flow, is the taint-tracking library, which finds how data can *influence* other values | |
| Data flow is particularly useful for security queries, where untrusted data flows to vulnerable parts of the program. Related to data flow is the taint-tracking library, which finds how data can *influence* other values |
|
|
||
| ## Overview | ||
|
|
||
| <!-- autogenerated CWE coverage table will be added below --> |
There was a problem hiding this comment.
I'm appreciative of the automation here!
| You can map a data flow ``ParameterNode`` to its corresponding ``Parameter`` AST node using the ``asParameter`` member predicate. | ||
| Similarly, you can use the ``asExpr`` member predicate to map a data flow ``ExprNode`` to its corresponding ``ExprCfgNode`` in the control-flow library. |
There was a problem hiding this comment.
The order of these two sentences is slightly distracting, as everywhere else we list expr nodes first and then parameter nodes.
| You can map a data flow ``ParameterNode`` to its corresponding ``Parameter`` AST node using the ``asParameter`` member predicate. | |
| Similarly, you can use the ``asExpr`` member predicate to map a data flow ``ExprNode`` to its corresponding ``ExprCfgNode`` in the control-flow library. | |
| You can use the ``asExpr`` member predicate to map a data flow ``ExprNode`` to its corresponding ``ExprCfgNode`` in the control-flow library. | |
| Similarly, you can map a data flow ``ParameterNode`` to its corresponding ``Parameter`` AST node using the ``asParameter`` member predicate. |
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| You can use the local data flow library by importing the ``codeql.rust.dataflow.DataFlow`` module. The library uses the class ``Node`` to represent any element through which data can flow. | ||
| ``Node``\ s are divided into expression nodes (``ExprNode``) and parameter nodes (``ParameterNode``). |
There was a problem hiding this comment.
This sounds like an exhaustive list but I think there are other kinds of nodes, e.g. flow summary nodes. I don't think we should bring them up here but maybe rephrase to something like:
| ``Node``\ s are divided into expression nodes (``ExprNode``) and parameter nodes (``ParameterNode``). | |
| Common ``Node`` types include expression nodes (``ExprNode``) and parameter nodes (``ParameterNode``). |
This should be kept unmerged until we get to the public preview phase.