Add QLDoc to ActiveRecord.qll

alexrford · alexrford · commit 762656ee60a7 · 2021-06-17T14:41:51.000+01:00
diff --git a/ql/src/codeql_ruby/frameworks/ActiveRecord.qll b/ql/src/codeql_ruby/frameworks/ActiveRecord.qll
@@ -18,6 +18,15 @@ private class ApplicationRecordAccess extends ConstantReadAccess {
   ApplicationRecordAccess() { this.getName() = "ApplicationRecord" }
 }
 
+/**
+ * A `ClassDeclaration` for a class that extends `ActiveRecord::Base`. For example,
+ *
+ * ```rb
+ * class UserGroup < ActiveRecord::Base
+ *   has_many :users
+ * end
+ * ```
+ */
 class ActiveRecordModelClass extends ClassDeclaration {
   ActiveRecordModelClass() {
     // class Foo < ActiveRecord::Base
@@ -33,7 +42,7 @@ class ActiveRecordModelClass extends ClassDeclaration {
   }
 }
 
-// A class method call whose receiver is an ActiveRecord model class
+/** A class method call whose receiver is an `ActiveRecordModelClass`. */
 class ActiveRecordModelClassMethodCall extends MethodCall {
   // The model class that receives this call, if any
   private ActiveRecordModelClass recvCls;
@@ -64,6 +73,20 @@ private predicate methodWithSqlFragmentArg(string methodName, int argIndex) {
   methodName = "calculate" and argIndex = 1
 }
 
+/**
+ * A method call that may result in executing unintended user-controlled SQL
+ * queries if the `getSqlFragmentSinkArgument()` expression is tainted by
+ * unsanitized user-controlled input. For example, supposing that `User` is an
+ * `ActiveRecord` model class, then
+ *
+ * ```rb
+ * User.where("name = '#{user_name}'")
+ * ```
+ *
+ * may be unsafe if `user_name` is from unsanitized user input, as a value such
+ * as `"') OR 1=1 --"` could result in the application looking up all users
+ * rather than just one with a matching name.
+ */
 class PotentiallyUnsafeSqlExecutingMethodCall extends ActiveRecordModelClassMethodCall {
   // The name of the method invoked
   private string methodName;
@@ -94,6 +117,11 @@ class PotentiallyUnsafeSqlExecutingMethodCall extends ActiveRecordModelClassMeth
   Expr getSqlFragmentSinkArgument() { result = sqlFragmentExpr }
 }
 
+/**
+ * An `SqlExecution::Range` for an argument to a
+ * `PotentiallyUnsafeSqlExecutingMethodCall` that may be vulnerable to being
+ * controlled by user input.
+ */
 class ActiveRecordSqlExecutionRange extends SqlExecution::Range {
   ActiveRecordSqlExecutionRange() {
     exists(PotentiallyUnsafeSqlExecutingMethodCall mc |
