devin_lifeguard.yaml

rules:
  - name: no-void-functions
    trigger: >-
      When implementing new public functions (WOLFSSL_API) avoid using "void"
      return type to ensure error values can be propagated upstream. Does not
      apply to "doc/" directory.
    solution: >-
      Change the function to return an appropriate error code or result instead
      of void. Ensure all return paths provide a meaningful value.
  - name: avoid-recursion
    trigger: >-
      Recursion is not allowed. Prefer iterative solutions to reduce stack usage
      and prevent potential stack overflows.
    solution: >-
      Refactor the recursive function into an iterative one using loops or other
      control structures.
  - name: use-forcezero
    trigger: >-
      Sensitive data such as private keys must be zeroized using `ForceZero()`
      to prevent the compiler from optimizing away the zeroization.
    solution: >-
      Replace `memset` or similar functions with `ForceZero(variable, size)` to
      ensure sensitive data is properly cleared from memory.
  - name: check-all-return-codes
    trigger: >-
      Every return code from function calls must be checked to handle errors
      appropriately and prevent unexpected behavior.
    solution: >-
      After each function call, add error handling logic to check the return
      value and respond accordingly.
  - name: no-memory-leaks
    trigger: >-
      Memory or resources allocated must have a clear path to being released to
      prevent memory leaks.
    solution: >-
      Ensure that every allocation has a corresponding free or release call. Use
      resource management patterns to handle allocations and deallocations.
  - name: do-not-change-external-apis
    trigger: >-
      External facing APIs should not be altered. Instead of modifying an
      existing API, create a new version with the necessary parameters.
    solution: >-
      If additional parameters are needed, create a new function (e.g., `f_ex(a,
      b)`) and have the original function (`f(a)`) call the new one with default
      or null parameters.
  - name: limit-stack-usage
    trigger: >-
      Functions should not use more than 100 bytes of stack. Excessive stack
      usage can lead to stack overflows and reduced performance.
    solution: >-
      Apply the `WOLFSSL_SMALL_STACK` pattern by dynamically allocating large
      variables to minimize stack usage within the function.
  - name: prefer-constant-time
    trigger: >-
      Any code handling secret or private key data (symmetric or asymmetric)
      must be implemented in constant time. This includes cryptographic
      operations, key comparisons, and encoding/decoding operations (base64,
      hex, etc.) when processing secrets. Use constant-time implementations
      by default for all secret data since tracking when timing attacks are
      strictly possible is error-prone.
    solution: >-
      Review and refactor code to ensure execution time does not depend on
      secret values. Use constant-time functions such as ConstantCompare()
      for comparisons and avoid early-exit conditions based on secret data.
      When in doubt, assume constant-time handling is required.
  - name: use-sizeof
    trigger: >-
      Avoid hard-coded numeric values for sizes. Use `sizeof()` to ensure
      portability and maintainability.
    solution: >-
      Replace hard-coded sizes with `sizeof(type)` to automatically adapt to
      changes in type sizes.
  - name: use-typedefs-not-stdint
    trigger: >-
      Use `byte`, `word16`, `word32` instead of standard integer types like
      `uint32_t` to maintain consistency across the codebase.
    solution: >-
      Replace instances of `uint32_t` and similar types with the designated
      typedefs such as `word32`.
  - name: use-c-style-comments
    trigger: >-
      Only C-style comments (`/* */`) are allowed in C code. C++ style comments
      (`//`) should not be used.
    solution: >-
      Replace all `//` comments with `/* */` to adhere to the project's
      commenting standards.
  - name: pointer-null-check
    trigger: >-
      Always check for null pointers using the `ptr != NULL` pattern to prevent
      dereferencing null pointers.
    solution: >-
      Add a condition to verify that the pointer is not null before using it,
      e.g., `if (ptr != NULL) { /* use ptr */ }`.
  - name: declare-const-pointers
    trigger: >-
      Pointer parameters that are not modified within a function should be
      declared as `const` to enhance code safety and clarity.
    solution: >-
      Add the `const` keyword to pointer parameters that are not intended to be
      modified, e.g., `const void *ptr`.
  - name: struct-member-order
    trigger: >-
      Struct members should be ordered in descending size to optimize memory
      alignment and reduce padding.
    solution: >-
      Reorder the members of the struct so that larger data types are declared
      before smaller ones.
  - name: no-always-success-stubs
    trigger: >-
      when implementing a stub function that is not fully developed, returning
      success unconditionally can hide real logic and debugging information
    solution: >-
      either implement the stub with real logic or return an appropriate error
      code to indicate "not yet implemented," so that failures are not silently
      ignored
  - name: free-allocated-memory
    trigger: |-
      allocating memory but forgetting to free it on all code paths
      or using functions that allocate buffers without a corresponding free
    solution: >-
      for every XMALLOC call, ensure there's a matching XFREE on every return
      path

      if handing ownership off, confirm the new owner also properly frees it
  - name: check-return-codes
    trigger: >-
      calling library functions that return non-zero in case of error, but not
      checking or handling those return values
    solution: >-
      always verify and handle function return codes

      if ret != 0, do not continue silently; either propagate the error or
      handle it
  - name: handle-partial-writes
    trigger: >-
      calling a write function (e.g., wolfSSL_write_ex) that may write only part
      of the data, returning fewer bytes than requested or a particular status
    solution: >-
      if partial writes are possible, loop until the entire buffer is written or
      an error occurs

      do not assume a single call wrote or accepted all bytes
  - name: manage-ephemeral-objects-correctly
    trigger: >-
      generating or importing ephemeral objects (e.g., ephemeral keys, ephemeral
      certs) and forgetting to finalize or free them, or double-freeing them
    solution: >-
      coordinate ephemeral object ownership carefully

      ensure ephemeral structures are freed once no longer needed, and avoid
      reusing pointers after free
  - name: use-proper-function-visibility
    trigger: >-
      functions must use appropriate visibility modifiers. Public functions
      should use WOLFSSL_API, local functions should use WOLFSSL_LOCAL, and
      non-static local functions should have a wolfssl_local_ or wc_local_ prefix.
    solution: >-
      for public functions that are part of the external API, declare them with
      WOLFSSL_API. For functions local to the library but not static, use
      WOLFSSL_LOCAL and prefix the function name with wolfssl_local_ or wc_local_
      to clearly indicate internal usage.