fix(main): add KAS allow list functionality

[b-long]

Fixes a critical Server-Side Request Forgery (SSRF) vulnerability.

The KAS URL normalization logic does not validate the destination host against a trusted allow-list. Since the SDK automatically includes the user's OIDC access token in the Authorization header when making requests to the KAS (e.g., during unwrap operations), an attacker can craft a malicious TDF file with a kas_url pointing to a server they control. When a victim attempts to open this TDF file, their OIDC access token will be leaked to the attacker's server.

[gemini-code-assist]

Summary of Changes

Hello @b-long, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the security posture of the SDK by implementing a KAS (Key Access Server) allow list. This feature is designed to prevent Server-Side Request Forgery (SSRF) vulnerabilities, which could arise if malicious TDF files attempt to direct the SDK to untrusted KAS endpoints for credential theft. The changes introduce a robust URL validation mechanism, integrate it seamlessly into the SDK's core components, and provide clear configuration options for users.

Highlights

• KAS Allowlist Functionality: Introduced a new KASAllowlist class and integrated it into the SDK to validate Key Access Server (KAS) URLs, preventing Server-Side Request Forgery (SSRF) attacks by ensuring the SDK only communicates with trusted KAS endpoints.
• CLI Argument Additions: Added new command-line arguments --kas-allowlist to specify a list of trusted KAS URLs and --ignore-kas-allowlist to disable KAS allowlist validation (with a warning for insecurity).
• SDK Builder and Client Integration: The SDKBuilder now allows configuring the KAS allowlist, and the KASClient uses this allowlist to validate KAS URLs before making requests. A new SDK.KasAllowlistException is introduced for validation failures.
• Code Style and Linter Update: Updated the Ruff linter version to v0.15.0 and applied minor code style improvements by replacing some if X else Y ternary operations with X or Y for conciseness.
• Comprehensive Testing: Added a new dedicated test file tests/test_kas_allowlist.py with extensive unit and integration tests covering various scenarios for the KAS allowlist, including origin normalization, exception handling, and SSRF protection.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• .pre-commit-config.yaml
  • Updated Ruff linter version from v0.14.8 to v0.15.0.
• src/otdf_python/cli.py
  • Refactored build_sdk by extracting authentication configuration into a new private helper function _configure_auth.
  • Added a new private helper function _configure_kas_allowlist to manage KAS allowlist settings.
  • Integrated _configure_kas_allowlist into the build_sdk function.
  • Introduced new CLI arguments: --kas-allowlist for specifying trusted KAS URLs and --ignore-kas-allowlist to disable validation.
• src/otdf_python/kas_allowlist.py
  • New file: Implemented the KASAllowlist class to manage and validate trusted KAS URLs, including methods for adding URLs, checking allowance, and raising exceptions on validation failure.
  • Added URL normalization logic to handle schemes, hosts, and ports consistently.
  • Included from_platform_url class method for convenient allowlist creation based on the platform URL.
• src/otdf_python/kas_client.py
  • Modified the __init__ method to accept an optional kas_allowlist instance.
  • Updated _normalize_kas_url to perform validation against the kas_allowlist before URL processing, raising SDK.KasAllowlistException if validation fails.
  • Minor code improvement in _handle_existing_scheme using parsed.path or "".
• src/otdf_python/nanotdf.py
  • Replaced if X else Y ternary operations with X or Y for improved readability and conciseness in _serialize_policy_object and _prepare_policy_data.
• src/otdf_python/sdk.py
  • Modified KASClient initialization to pass the kas_allowlist parameter.
  • Added a new exception class SDK.KasAllowlistException to provide detailed information when a KAS URL is rejected by the allowlist.
• src/otdf_python/sdk_builder.py
  • Imported KASAllowlist.
  • Added internal attributes _kas_allowlist_urls and _ignore_kas_allowlist to store allowlist configuration.
  • Introduced new builder methods: with_kas_allowlist to set explicit trusted KAS URLs and with_ignore_kas_allowlist to control allowlist validation.
  • Implemented _create_kas_allowlist helper method to construct the KASAllowlist instance based on builder settings.
  • Modified _create_services to instantiate KASClient with the configured kas_allowlist.
• src/otdf_python/tdf.py
  • Replaced if X else Y ternary operations with X or Y for improved readability and conciseness in _serialize_policy_object.
• tests/config_pydantic.py
  • Applied minor formatting adjustment to the OIDC_OP_TOKEN_ENDPOINT default factory.
• tests/support_otdfctl_args.py
  • Replaced if X else Y ternary operations with X or Y for improved readability and conciseness in _generate_target_mode_tdf.
• tests/test_kas_allowlist.py
  • New file: Added comprehensive unit and integration tests for the KASAllowlist class, its integration with KASClient, and configuration via SDKBuilder.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/platform-integration-test.yaml

Activity

• The pull request introduces a new security feature, the KAS allowlist, to protect against SSRF attacks.
• New CLI arguments have been added to allow users to configure this security feature.
• The core SDK components (KASClient, SDKBuilder) have been updated to integrate the new allowlist functionality.
• A new test file with extensive test cases has been added, demonstrating thorough testing of the new feature.
• Minor code style improvements were made across several files for consistency and readability.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a KAS allowlist feature, a significant security enhancement designed to prevent SSRF attacks and credential theft from malicious TDF files by ensuring authentication tokens are sent only to trusted Key Access Service endpoints. While the implementation is well-structured and tested, a medium-severity issue was identified where client secrets could be leaked into logs when using the legacy --auth CLI argument with malformed input. Additionally, a suggestion is made to improve the SDKBuilder to ensure more predictable and secure allowlist behavior by default when an explicit list of URLs is provided.