Skip to content

docs: Add 'Customizing library models for Rust' documentation#21727

Draft
coadaflorin wants to merge 5 commits intomainfrom
docs/customizing-library-models-for-rust
Draft

docs: Add 'Customizing library models for Rust' documentation#21727
coadaflorin wants to merge 5 commits intomainfrom
docs/customizing-library-models-for-rust

Conversation

@coadaflorin
Copy link
Copy Markdown
Contributor

Summary

Adds a new documentation page: Customizing library models for Rust, following the pattern of existing documentation for other languages:

What's included

The documentation covers Rust-specific concepts:

  • Extensible predicates: sourceModel, sinkModel, summaryModel, neutralModel with Rust's simplified 3-5 column schema (vs Java/Go's 9-10 column schema)
  • Canonical paths: How Rust identifies callables using fully-qualified paths (crate::module::function, <Type>::method, <Type as Trait>::method, <_ as Trait>::method)
  • Rust-specific access path tokens: Reference (for &T), Future (for async), Field with Rust enum variant syntax
  • Examples using real models from the codebase:
    • SQL injection sink with sqlx
    • Remote source from reqwest::get
    • Environment variable source from std::env::var
    • Flow summary through reqwest::Response::text (async)
    • Flow summary through std::path::Path::join (multiple inputs)
    • Flow summary through Iterator::map (higher-order, wildcard trait)
    • Neutral model for Option::map
  • Reference sections for predicates, access paths, source/sink/summary kinds, and threat models

Changes

  • New file: docs/codeql/codeql-language-guides/customizing-library-models-for-rust.rst
  • Modified: docs/codeql/codeql-language-guides/codeql-for-rust.rst — added toctree entry and description

Add documentation for customizing library models for Rust using data
extension files. This follows the pattern of existing documentation for
other languages (Java, Python, Ruby, Go, C#, C++, JavaScript).

The documentation covers:
- Rust-specific extensible predicates (sourceModel, sinkModel,
  summaryModel, neutralModel) with their simplified schema
- Canonical path syntax for identifying Rust functions and methods
- Examples using real models from the codebase (sqlx, reqwest,
  std::env, std::path, Iterator::map)
- Access path token reference (Argument, Parameter, ReturnValue,
  Element, Field, Reference, Future)
- Source and sink kind reference
- Threat model integration

Also updates codeql-for-rust.rst to include the new page in the
toctree.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add barrierModel and barrierGuardModel sections to the Rust library
models documentation, following the pattern established in PR #21523
for other languages.

Includes:
- New extensible predicate descriptions in the overview
- Example: barrier for SQL injection using escape_sql
- Example: barrier guard for path injection using is_safe_path
- Reference material for both barrierModel and barrierGuardModel

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

@geoffw0 geoffw0 left a comment

Choose a reason for hiding this comment

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

Partially reviewed. I need to continue from "Examples of custom model definitions", then check final rendering and links. We will also want a docs team review at some point.

Comment thread docs/codeql/codeql-language-guides/codeql-for-rust.rst Outdated
- ``data`` defines one or more rows of tuples that are injected as values into the extensible predicate. The number of columns and their types must match the definition of the extensible predicate.

Data extensions use union semantics, which means that the tuples of all extensions for a single extensible predicate are combined, duplicates are removed, and all of the remaining tuples are queryable by referencing the extensible predicate.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We appear to be missing the "Publish data extension files in a CodeQL model pack to share" section that most of the other languages have, e.g. here. I think it can be copied in word-for-word.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I asked Copilot to add one for me and it did below.

Comment thread docs/codeql/codeql-language-guides/customizing-library-models-for-rust.rst Outdated
- **Free functions**: ``crate::module::function``, for example ``std::env::var`` or ``std::fs::read_to_string``.
- **Inherent methods**: ``<Type>::method``, for example ``<std::fs::File>::open``.
- **Trait methods with a concrete type**: ``<Type as Trait>::method``, for example ``<std::fs::File as std::io::Read>::read_to_end``.
- **Trait methods with a wildcard type**: ``<_ as Trait>::method``, for example ``<_ as core::clone::Clone>::clone``. This form matches any type that implements the trait and is useful for modeling broadly applicable trait methods.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't see this section in the doc for other languages, I think Copilot may have synthesised it entirely ... but it looks really helpful, and as far as I can tell, correct.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

As someone with no familiarity with rust, it looks helpful to me. (Assuming it's correct.)

coadaflorin and others added 3 commits April 17, 2026 15:11
…for-rust.rst

Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>
Co-authored-by: Geoffrey White <40627776+geoffw0@users.noreply.github.com>
Add the 'Publish data extension files in a CodeQL model pack to share'
section, matching the structure used in C#, C++, Go, and Java docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants