@appland/scanner 1.40.3 → 1.44.0

package/doc/labels/security.authorization.md

@@ -0,0 +1,9 @@
+---
+name: security.authorization
+rules:
+  - authz-before-authn
+---
+
+Test whether the current authenticated user has permission to make a web request.
+
+Returns `truthy` if the request is allowed; otherwise `falsey`.

package/doc/labels/security.logout.md

@@ -0,0 +1,9 @@
+---
+name: security.logout
+rules:
+  - logout-without-session-reset
+---
+
+Logs out an application user.
+
+The function is assumed to be successful regardless of the return value.

package/doc/labels/string.equals.md

@@ -0,0 +1,18 @@
+---
+name: string.equals
+rules:
+  - insecure-compare
+---
+
+Compares two strings for equality.
+
+The function receiver should be a string, and the function should take one argument that is the
+other string.
+
+Returns `truthy` if the strings are equal; otherwise `falsey`.
+
+## Examples
+
+- Ruby [String#==](https://ruby-doc.org/core-3.1.0/String.html#method-i-3D-3D)
+- Java
+  [String#equals](<https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html#equals(java.lang.Object)>)

package/doc/rules/authzBeforeAuthn.md

@@ -0,0 +1,47 @@
+---
+rule: authz-before-authn
+name: Authz before authn
+title: Authorization performed before authentication
+references:
+  CWE-863: https://cwe.mitre.org/data/definitions/863.html
+impactDomain: Security
+labels:
+  - security.authorization
+  - security.authentication
+scope: http_server_request
+---
+
+Determines when authorization logic is applied to a user identity that has not been properly
+verified. Because the the user's identity has not been verified yet, the outcome of the
+authorization check cannot be trusted. A malicious user might be able to get themselves authorized
+as a different user than they really are - or they may not be logged in at all.
+
+### Rule logic
+
+Iterates over all descendants of the HTTP server request. If an event labeled
+`security.authentication` is encountered, the rule is satisfied. If an event labeled
+`security.authorization` is encountered, and the event returns a truthy value, the descendants of
+the authentication event are searched for an event labeled `security.authentication`. If such an
+event is found, the rule is satisfied. Otherwise a finding is emitted.
+
+### Notes
+
+A `security.authorization` event which returns a falsey value (`false`, `null`, etc) will not
+trigger a finding.
+
+The `security.authentication` event must return a truthy value (`true`, any object) in order to
+satisfy the rule.
+
+### Resolution
+
+Ensure that the user's identity is established before performing authorization.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: authzBeforeAuthn
+```

package/doc/rules/circularDependency.md

@@ -0,0 +1,57 @@
+---
+rule: circular-dependency
+name: Circular dependency
+title: Circular package dependency
+references:
+  CWE-1047: https://cwe.mitre.org/data/definitions/1047.html
+impactDomain: Maintainability
+scope: command
+---
+
+Finds cycles in the package dependency graph. Cyclic dependencies make code hard to maintain,
+because all the code in the cycle is inter-dependent. While it might look like the code in the
+different packages has separate functions, in essence all the code in the cycle acts like one big
+package.
+
+### Rule logic
+
+Builds the package dependency graph, in which each package is a graph node, and each function call
+from one package to another is an edge. The edges are directional, pointing from the caller package
+to the callee package.
+
+A graph traversal finds cycles - a cycle being a path which starts with a package (a node),
+traverses through other packages (via edges), and returns to the original package.
+
+For each package cycle that's detected in the call graph, the rule then searches for a sequence of
+function calls that matches the cycle. This sequence of events is returned in the finding.
+
+### Notes
+
+There may be multiple paths through the event trace that produce a given package cycle. Only one of
+these paths is reported in the finding.
+
+### Resolution
+
+If a package in the circular dependency is designed to call back into the code that call it, it can
+be added to the `ignoredPackages` list. This is common with helper and middleware code.
+
+Otherwise, you can fix the cyclic dependency by refactoring the code. One way to do this is to
+refactor some of the code into a new package, class, or library.
+
+### Options
+
+- `depth`. Minimum number of packages in a path that will be reported. Default: 4.
+- `ignoredPackages: ` [MatchPatternConfig](/docs/analysis/match-pattern-config.html)`[]`. Packages
+  which match this pattern are not included in the dependency graph. Default: empty - including all
+  packages.
+
+### Examples
+
+```yaml
+- rule: circularDependency
+  properties:
+    depth: 4 # default
+    ignoredPackages:
+      - equal: activesupport
+      - equal: app/helpers
+```

package/doc/rules/deserializationOfUntrustedData.md

@@ -0,0 +1,55 @@
+---
+rule: deserialization-of-untrusted-data
+name: Deserialization of untrusted data
+title: Deserialization of untrusted data
+references:
+  CWE-502: https://cwe.mitre.org/data/definitions/502.html
+  Ruby Security: https://docs.ruby-lang.org/en/3.0/doc/security_rdoc.html
+impactDomain: Security
+labels:
+  - deserialize.unsafe
+  - deserialize.safe
+  - sanitize
+---
+
+Finds occurrances of deserialization in which the mechanism employed is known to be unsafe, and the
+data is not known to be trusted.
+
+### Rule logic
+
+Finds all events labeled `deserialize.unsafe`, that are not a descendant of an event labeled
+`deserialize.safe`. For each of these events, all event parameters are checked.
+
+Each parameter whose type is `string` or `object` is verified to ensure that it's trusted. For data
+to be trusted, it must be the return value of a function labeled `sanitize`.
+
+### Notes
+
+With insecure deserialization, it is usually possible for an attacker to craft a malicious payload
+that executes code shortly after deserialization.
+
+### Resolution
+
+If you can guarantee that you are using unsafe deserialization in a safe way, but it's not possible
+to obtain the raw data from a function labeled `sanitize`, you can wrap the deserialization in a
+function labeled `deserialize.safe`.
+
+If you need to deserialize untrusted data, JSON is often a good choice as it is only capable of
+returning ‘primitive’ types such as strings, arrays, hashes, numbers and nil. If you need to
+deserialize other classes, you should handle this manually. Never deserialize to a user specified
+class¹.
+
+Ensure that the JSON library provided by your language and framework does not perform unsafe
+deserialization.
+
+1. https://docs.ruby-lang.org/en/3.0/doc/security_rdoc.html
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: deserializationOfUntrustedData
+```

package/doc/rules/http500.md

@@ -0,0 +1,36 @@
+---
+rule: http-500
+name: HTTP 500
+title: HTTP 500 status code
+references:
+  CWE-392: https://cwe.mitre.org/data/definitions/392.html
+impactDomain: Stability
+scope: http_server_request
+---
+
+Identifies when an HTTP server requset has returned a 500 status code. HTTP 500 status code
+generally indicate an unanticipated problem in the backend that is not handled in a predictable way.
+500 status codes are also hard for client code to handle, because they don't indicate any particular
+problem or suggest a solution.
+
+### Rule logic
+
+An HTTP 500 status code that's returned by an HTTP server request will be emitted as a finding by
+this rule.
+
+### Resolution
+
+The execution trace of request may show an unhandled exception. Or it may show exception or error
+handling that failed in some way, and was caught and handled generically by the framework. Use the
+trace to figure out the root cause of the problem, and update the code to report the problem using a
+more informative HTTP status code.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: http500
+```

package/doc/rules/illegalPackageDependency.md

@@ -0,0 +1,50 @@
+---
+rule: illegal-package-dependency
+name: Illegal package dependency
+title: Illegal use of code by a non-whitelisted package
+references:
+  CWE-1120: https://cwe.mitre.org/data/definitions/1120.html
+  CWE-1154: https://cwe.mitre.org/data/definitions/1154.html
+impactDomain: Maintainability
+scope: command
+---
+
+Ensures that all calls to a specified `callee` package come from an approved `caller` package. This
+is a way of defining and enforcing an architectural constraint that may not be provided by the
+programming language itself.
+
+### Rule logic
+
+All packages which call the `calleePackage` are inspected. Each one must match one of the
+`callerPackage` options.
+
+### Notes
+
+Many programming languages do not provide a way to make a package "private" or "protected" in the
+same way as a class or function. Yet, it's often desirable to limit the places from which code in a
+certain package can be called. This rule provides a way to define and enforce this type of
+architectural constraint.
+
+### Resolution
+
+The code which is illegally calling into the `calleePackage` should be refactored to call one of the
+allowed `callerPackages` instead. If the needed functionality is not available on a `callerPackage`,
+then one of the `callerPackages` should be modified to provide it.
+
+### Options
+
+- `callerPackages: ` [MatchPatternConfig](/docs/analysis/match-pattern-config.html)`[]`. Packages
+  which are allowed to call the `calleePackage`. Required.
+- `calleePackage: `[MatchPatternConfig](/docs/analysis/match-pattern-config.html). Package whose
+  callers should be checked. Required.
+
+### Examples
+
+```yaml
+- rule: illegalPackageDependency
+  properties:
+    callerPackages:
+      - equal: actionpack
+    calleePackage:
+      equal: app/controllers
+```

package/doc/rules/incompatibleHttpClientRequest.md

@@ -0,0 +1,35 @@
+---
+rule: incompatible-http-client-request
+name: Incompatible HTTP client request
+title: Incompatible HTTP client request
+impactDomain: Stability
+scope: http_client_request
+---
+
+Detects HTTP client requests which are incompatible with a published OpenAPI schema.
+
+### Rule logic
+
+Each HTTP client request is converted to an OpenAPI schema document. This is done by examining the
+request method, request URI, parameters, body, headers, etc. and representing them as OpenAPI. Then,
+the client OpenAPI schema is compared to the published server OpenAPI schema. If any breaking
+changes are detected between the client request and the published server schema, these are reported
+as findings.
+
+### Resolution
+
+Modify the HTTP client request to conform to the published schema.
+
+### Options
+
+- `schemata: Record<string, string>` A map from server hostnames to schema URLs. A schema must be
+  provided for each server hostname that's invoked in the AppMap.
+
+### Examples
+
+```yaml
+- rule: incompatibleHttpClientRequest
+  parameters:
+    schemata:
+      'myserver:8080': https://github.com/mycorp/myserver/tree/main/openapi.yaml
+```

package/doc/rules/insecureCompare.md

@@ -0,0 +1,59 @@
+---
+rule: insecure-compare
+name: Insecure compare
+title: Insecure comparison of secrets
+references:
+  CWE-208: https://cwe.mitre.org/data/definitions/208.html
+impactDomain: Security
+labels:
+  - secret
+  - string.equals
+---
+
+Identifies cases in which secrets are being compared directly using `string.equals`.
+
+Ordinary string comparison of user-provided data with a piece of secret data can leak information
+about the secret through [timing attacks](https://en.wikipedia.org/wiki/Timing_attack), because of
+short-circuting (returning false on first mismatch). This can allow the attacker to significantly
+speed up brute forcing, turning an intractable exponential problem into a linear one.
+
+### Rule logic
+
+The rule looks for events labeled `secret` and `string.equals`.
+
+On encountering an event labeled `secret` it remembers the return value.
+
+On encountering `string.equals` it looks at the arguments and the receiver. If any of the arguments
+is a previously seen secret, or matches a list of known secret-like regular expressions, the
+comparison is flagged as insecure, unless any of the arguments is a BCrypt digest.
+
+### Notes
+
+When generating appmaps, ensure that string comparison functions (such as `String#==` in Ruby and
+`String.equals` in Java) are traced and correctly labeled with `string.equals`. Any functions you
+know to return a secret (eg. a model accessor for an API key) should be labeled `secret`.
+
+Since using this rule generally requires labeling all string comparisons its use is currently
+limited due to performance and space overhead of tracing them: string comparisons are commonly used
+throughout the code base and libraries.
+
+It's advisable to only trace string equality on a limited subset of tests (perhaps the ones known to
+touch secret related functionality); alas, this is not something easily attainable with current
+AppMap recorders and requires swapping or modifying configuration files.
+
+### Resolution
+
+To fix this issue, either hash values before comparing or use a constant-time comparison in such
+operations. Constant-time comparison functions always compare every character of the string,
+removing the timing side channel. You can usually find functions like this in cryptographic and
+utility libraries, eg. `ActiveSupport::SecurityUtils.secure_compare`.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: insecureCompare
+```

package/doc/rules/jobNotCancelled.md

@@ -0,0 +1,49 @@
+---
+rule: job-not-cancelled
+name: Job not cancelled
+title: Job created in a rolled back transaction and not cancelled
+references:
+  CWE-672: https://cwe.mitre.org/data/definitions/672.html
+impactDomain: Stability
+labels:
+  - job.create
+  - job.cancel
+scope: transaction
+---
+
+Finds jobs which are created in a transaction, and not cancelled when the transaction is rolled
+back.
+
+### Rule logic
+
+THe rule identifies SQL transaction boundaries by examining the SQL queries for `START TRANSACTION`,
+`ROLLBACK`, `COMMIT`, etc.
+
+Within each transaction, the rule looks for events labeled `job.create`. If the transaction is
+rolled back, and there is not a corresponding event labeled `job.cancel`, then a finding is
+reported.
+
+### Notes
+
+It's recommended to program delayed jobs defensively to check for data and silently do nothing if
+that data is missing (eg. due to a rollback or a duplicate job); job details in this design are
+stored in the database and the queue entries only reference them.
+
+This rule is designed for use when this practice is impossible or not followed, and with external
+job queues that do not automatically roll back with the transaction. If the job queue is the
+database and the same connection is used for the job queue and for the request, then this check is
+not needed.
+
+### Resolution
+
+Cancel any queued jobs when the transaction rolls back.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: jobNotCanceled
+```

package/doc/rules/logoutWithoutSessionReset.md

@@ -0,0 +1,40 @@
+---
+rule: logout-without-session-reset
+name: Logout without session reset
+title: Logout without session reset
+references:
+  CWE-488: https://cwe.mitre.org/data/definitions/488.html
+  OWASP - Session fixation: https://owasp.org/www-community/attacks/Session_fixation
+  Ruby on Rails - Session fixation countermeasures: >-
+    https://guides.rubyonrails.org/security.html#session-fixation-countermeasures
+impactDomain: Security
+labels:
+  - http.session.clear
+  - security.logout
+scope: http_server_request
+---
+
+Determines when a user has been logged out from the application, but the session hasn't been
+cleared. When the session isn't cleared after logout, the session is vulnerable to a
+[session fixation attack](https://owasp.org/www-community/attacks/Session_fixation).
+
+### Rule logic
+
+Iterates over all descendants of the HTTP server request. If an event labeled `security.logout` is
+encountered, the event must have a descendant labeled `http.session.clear`, otherwise a finding is
+emitted.
+
+### Notes
+
+Return values from `security.logout` and `http.session.clear` are not checked, as these methods are
+assumed to always succeed.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: logoutWithoutSessionReset
+```

package/doc/rules/missingAuthentication.md

@@ -0,0 +1,59 @@
+---
+rule: missing-authentication
+name: Missing authentication
+title: Unauthenticated HTTP server request
+references:
+  CWE-306: https://cwe.mitre.org/data/definitions/306.html
+impactDomain: Security
+labels:
+  - public
+  - security.authentication
+scope: http_server_request
+---
+
+An HTTP server request is missing authentication. In this case, the request may be serving assets
+that should be protected by authentication - but no authentication is actually happening.
+
+### Rule logic
+
+This rule checks all HTTP server requests that satisfy the following conditions:
+
+- HTTP status code is `< 300`
+- Matches include and exclude lists of content type (by default, these are empty).
+
+For each matching request, any event that satisfies either of these conditions will satisfy the rule:
+
+1. Has label `public`.
+2. Has label `security.authentication`, and returns a truthy value.
+
+### Notes
+
+If a request does not require an authenticated user (e.g. because it contains completely public
+information), then this rule can be satisfied by calling any function labeled `public`.
+
+If the `security.authentication` event returns a falsey value (`false`, `null`, etc), then
+authentication is assumed to be denied, and the rule is not satisfied.
+
+### Resolution
+
+If the request is designed to be public, and the omission of authentication is intentionaly, modify
+the code so that it calls a function labeled `public`.
+
+Otherwise, modify the code so that it calls a function labeled `security.authentication` which
+returns a truthy result (for example, a User object).
+
+### Options
+
+- `includeContentTypes: ` [MatchPatternConfig](/docs/analysis/match-pattern-config.html)`[]`.
+  Default: empty - including all content types.
+- `excludeContentTypes: ` [MatchPatternConfig](/docs/analysis/match-pattern-config.html)`[]`.
+  Default: empty - excluding no content types.
+
+### Examples
+
+```yaml
+- rule: missingAuthentication
+  properties:
+    includeContentTypes:
+      - match: ^application/json
+```

package/doc/rules/missingContentType.md

@@ -0,0 +1,33 @@
+---
+rule: missing-content-type
+name: Missing content type
+title: HTTP server request without a Content-Type header
+impactDomain: Stability
+scope: http_server_request
+---
+
+Finds HTTP server requests that don't provide a `Content-Type` header in the response.
+
+### Rule logic
+
+Every HTTP server request is checked. If the status code indicates redirect or "No content", then
+the rule passes. Otherwise, a finding is issued if the response is missing a `Content-Type` header.
+
+### Notes
+
+When a response is missing the `Content-Type` header, it's unclear to clients how to handle the
+response data. Bugs are likely to result.
+
+### Resolution
+
+Provide a `Content-Type` in the response.
+
+### Options
+
+None
+
+### Examples
+
+```yaml
+- rule: missingContentType
+```

package/doc/rules/nPlusOneQuery.md

@@ -0,0 +1,52 @@
+---
+rule: n-plus-one-query
+name: N plus one query
+title: N plus 1 SQL query
+references:
+  CWE-1073: https://cwe.mitre.org/data/definitions/1073.html
+impactDomain: Performance
+scope: command
+---
+
+
+Finds occurrences of a query being repeated within a loop.
+
+### Rule logic
+
+Within each command, SQL queries are normalized, grouped, and counted.
+
+If the number of duplicate instances of a normalized query exceeds the threshold, it's reported as a
+finding.
+
+### Notes
+
+N plus one queries typically occur when a
+[data access object (DAO)](https://en.wikipedia.org/wiki/Data_access_object) has a one-to-many or
+many-to-many relationship, and the relationship is enumerated within a loop. The DAO will issue a
+separate query to fetch each related record. If the number of related objects is large, or if each
+one is fairly expensive to fetch, application performance suffers.
+
+### Resolution
+
+DAO libraries typically offer a feature called "eager loading". For example:
+
+- [ActiveRecord](https://news.learnenough.com/eager-loading)
+- [Django ORM](https://docs.djangoproject.com/en/4.0/topics/db/optimization/#retrieve-everything-at-once-if-you-know-you-will-need-it)
+- [Hibernate](https://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/jpamodelgen/xml/jaxb/FetchType.html)
+
+Enable eager loading on the association in question to fetch the data efficiently, without repeated,
+identical queries.
+
+### Options
+
+- `warningLimit` Threshold for reporting a warning. Default: 5.
+- `errorLimit` Threshold for reporting an error. Default: 10.
+
+### Examples
+
+```yaml
+- rule: nPlusOneQuery
+  parameters:
+    warningLimit: 5
+    errorLimit: 10
+```

package/doc/rules/queryFromInvalidPackage.md

@@ -0,0 +1,45 @@
+---
+rule: query-from-invalid-package
+name: Query from invalid package
+title: Queries from invalid packages
+references:
+  CWE-1057: https://cwe.mitre.org/data/definitions/1057.html
+impactDomain: Maintainability
+---
+
+Ensures that SQL queries are made only from an approved list of packages. This helps to make the
+code more maintainable by encapsulating access to the database.
+
+### Notes
+
+When too many packages are performing direct SQL queries, it's very hard to keep the code modular.
+The result is a lack of coherent design and degredation in maintainability.
+
+### Rule logic
+
+All functions which make SQL queries are inspected. Each one must match one of the
+`allowedPackages`.
+
+### Resolution
+
+The code which is making the direct query should be refactored to use the database through one of
+the allowed packages.
+
+### Options
+
+- `allowedPackages: `[MatchPatternConfig](/docs/analysis/match-pattern-config.html)`[]`. Packages
+  which are allowed to make queries. Required.
+- `allowedQueries: `[MatchPatternConfig](/docs/analysis/match-pattern-config.html)`[]`. Queries which
+  are allowed from anywhere. Default:
+  `[/\bBEGIN\b/i, /\bCOMMIT\b/i, /\bROLLBACK\b/i, /\bRELEASE\b/i, /\bSAVEPOINT\b/i]`.
+
+### Examples
+
+```yaml
+- rule: queryFromInvalidPackage
+  properties:
+    callerPackages:
+      - equal: actionpack
+    calleePackage:
+      equal: app/controllers
+```