scan.yaml

# The questions perch asks of every method it reads. Shipped with the package; perch.yaml overrides or adds by name.
#
# Each entry is one typed question. A noul comes back as a probability, a choice as a distribution over options, a score as a
# distribution over the rubric's levels. `issue:` says what an answer means: which bucket it files under, what it is labelled,
# and whether the issue is the true answer or the false one. A question with no `issue:` is asked for another question's sake.
#
# Two names are reserved. `severity` is the rubric correctness issues are weighted by, and `kind` is what `label: kind` reads.
#
# What is not here is not a question: which line a defect is on, which method to read next, and how much of a neighbourhood fits
# in one request are how perch works rather than what it asks, and they live in src/questions.js.

- name: has_bug
  each: method
  where: "**/*"
  ask: Does `method` contain a concrete behavioral defect that a caller can reach?
  true: >
    For some input a caller can pass, the method returns a wrong result, leaves
    wrong state, throws when it should not, or fails to throw when it should
  false: >
    The method behaves correctly for every input its callers can pass; style,
    performance, and hypothetical misuse do not count
  issue: { type: defect, label: kind }
  min: 60

- name: kind
  type: choice
  each: method
  where: "**/*"
  ask: If `method` has a defect, which kind is it?
  options:
    boundary: An off-by-one, a wrong comparison, or a mishandled edge of a range
    missing_null_handling: A null, undefined, empty, or absent value is not handled
    wrong_return: The wrong value, or a value of the wrong shape, is returned for some input
    swallowed_error: An error is caught, ignored, or turned into a misleading result
    state_mutation: Shared or input state is mutated when it should not be, or left
      stale when it should change
    ordering: Operations run in the wrong order, or rely on an order that is not
      guaranteed
    resource_leak: A handle, lock, timer, process, or connection is not released on some path
    inverted_condition: A condition, sign, or boolean is the wrong way round

- name: severity
  type: score
  each: method
  where: "**/*"
  ask: If something is wrong with `method`, how much would a caller feel it?
  # Weakest first. The bands run the other way, so the top level is P0.
  levels:
    - No caller would notice
    - A wrong result in a rare case, or one the caller can see and recover from
    - A wrong result or wrong state in ordinary use
    - Data lost, corrupted, or exposed, or a check that should stop someone
      bypassed

- name: refactor
  type: choice
  each: method
  where: "**/*"
  ask: >
    Judging from `method`, its `metrics` (risk_score and maintainability_index
    run 0-100, cyclomatic_complexity and max_nesting are counts), and how its
    callers use it, what does it most need?
  options:
    split: Does too many things; split it into smaller methods with one job each
    flatten: Nested too deeply; flatten with early returns or extracted helpers
    simplify_conditions: Conditions are hard to follow; simplify or name them
    deduplicate: Repeats logic that exists elsewhere in the shown code; reuse it
    rename: The name or parameters misdescribe what it does; rename them
    remove_dead_code: Contains unreachable or unused code; remove it
    none: No refactor needed
  issue: { type: refactor, label: refactor, except: none }
  min: 60

- name: does_what_it_claims
  each: method
  where: "**/*"
  ask: >-
    Does `method` do what its name, its parameters and its `leading_comment` say
    it does?
  true: It behaves the way its name and its comment say it does
  false: >-
    It does something different from, less than, or more than its name and
    comment say, so one of the two is wrong
  issue:
    type: defect
    label: does_not_do_what_it_claims
    on: false
  min: 70

- name: documented
  each: method
  where: "**/*"
  ask: >-
    Could a caller learn what `method` promises from its `leading_comment`, or
    from the code itself where it is small enough to read?
  true: >-
    Its contract, its edge cases and its side effects are all there to be read
  false: >-
    A caller could not learn what it promises without reading it through. A
    comment that says something untrue is misaligned rather than this: this is
    what is missing.
  issue:
    type: docs
    label: docs
    on: false
  min: 75

# A gate. It raises nothing itself; `when: exposed` multiplies a class by it.
- name: exposed
  each: method
  where: "**/*"
  ask: >-
    Does a value chosen by someone outside this program reach `method`, or does
    `method` act outside the program on such a value?
  true: >-
    Something a person or another system chose reaches it, such as a request, an
    argument, a message, a row, or a file whose name or contents they control;
    or it runs, queries, writes or sends using such a value.
  false: >-
    Everything it works on was decided by this program, and anything it touches
    outside is named by this program.

# The vulnerability classes. One noul each, all filed under security, the likeliest one listed. `when: exposed` marks the ones
# that only matter when something from outside reaches the method; the rest are wrong on their own terms. Gating those once hid a
# use-after-free rated at 95% behind a method perch was only 46% sure took outside input.

- name: injection
  each: method
  where: "**/*"
  when: exposed
  ask: >
    If `method` handles anything from outside the program: is this true of it? A
    value from outside is put into a shell command, a query, a path of
    execution, or anything that gets evaluated, without being escaped or
    parameterised.
  true: >
    Yes: a value from outside is put into a shell command, a query, a path of
    execution, or anything that gets evaluated, without being escaped or
    parameterised
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: path_traversal
  each: method
  where: "**/*"
  when: exposed
  ask: >
    If `method` handles anything from outside the program: is this true of it? A
    name from outside is used to build a filesystem path, URL, or key without
    being confined to the place it is meant to reach.
  true: >
    Yes: a name from outside is used to build a filesystem path, URL, or key
    without being confined to the place it is meant to reach
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: unsafe_deserialization
  each: method
  where: "**/*"
  when: exposed
  ask: >-
    If `method` handles anything from outside the program: is this true of it?
    Data from outside is turned into code, or into an object whose type it
    chose. eval, new Function or a vm run over it; a deserializer that can
    instantiate arbitrary classes; a YAML or XML parser with tags or entities
    enabled; a merge that lets it set __proto__ or constructor. Parsing outside
    data into plain values is not this, however untrusted it is.
  true: >-
    Yes: data from outside is turned into code, or into an object whose type it
    chose. eval, new Function or a vm run over it; a deserializer that can
    instantiate arbitrary classes; a YAML or XML parser with tags or entities
    enabled; a merge that lets it set __proto__ or constructor. Parsing outside
    data into plain values is not this, however untrusted it is.
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: secret_exposure
  each: method
  where: "**/*"
  when: exposed
  ask: >
    If `method` handles anything from outside the program: is this true of it? A
    password, token, key, or other credential is written into the source,
    logged, returned to a caller, or sent somewhere it need not go.
  true: >
    Yes: a password, token, key, or other credential is written into the source,
    logged, returned to a caller, or sent somewhere it need not go
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: missing_authorization
  each: method
  where: "**/*"
  when: exposed
  ask: >
    If `method` handles anything from outside the program: is this true of it?
    An action that should check who is asking, or what they may touch, does not
    check, or checks after it has already acted.
  true: >
    Yes: an action that should check who is asking, or what they may touch, does
    not check, or checks after it has already acted
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: weak_crypto
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    Security rests on predictable randomness, a home-made scheme, a broken
    algorithm, or a comparison that leaks timing
  false: Nothing in `method` does this.
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: unvalidated_destination
  each: method
  where: "**/*"
  when: exposed
  ask: >
    If `method` handles anything from outside the program: is this true of it?
    An address, host, or redirect target from outside decides where a request or
    a user is sent.
  true: >
    Yes: an address, host, or redirect target from outside decides where a
    request or a user is sent
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: resource_exhaustion
  each: method
  where: "**/*"
  when: exposed
  ask: >-
    If `method` handles anything from outside the program: is this true of it?
    Input from outside decides how much memory, recursion, time or work happens,
    and nothing bounds it. Work whose size is what the operator asked for is not
    this: a tool doing as much work as the input it was pointed at is doing its
    job.
  true: >-
    Yes: input from outside decides how much memory, recursion, time or work
    happens, and nothing bounds it. Work whose size is what the operator asked
    for is not this: a tool doing as much work as the input it was pointed at is
    doing its job.
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: unsafe_reflection
  each: method
  where: "**/*"
  when: exposed
  ask: >-
    If `method` handles anything from outside the program: is this true of it? A
    name from outside chooses which function, class, field or module is reached,
    so it picks code the program never named. An import or require built from
    it, a property taken off an object and called, a class or handler resolved
    by name. A lookup in a table the program itself wrote, where a name that is
    not in it is handled, is not this.
  true: >-
    Yes: a name from outside chooses which function, class, field or module is
    reached, so it picks code the program never named. An import or require
    built from it, a property taken off an object and called, a class or handler
    resolved by name. A lookup in a table the program itself wrote, where a name
    that is not in it is handled, is not this.
  false: No, or nothing from outside reaches this method
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: disabled_safeguard
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    A check that exists is turned off or weakened: certificate verification
    skipped, a permission widened, a warning suppressed, a sandbox opened
  false: Nothing in `method` does this.
  issue: { type: security, label: self, pick: strongest }
  min: 70

- name: buffer_overflow
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    An index, length or offset reaches past the end of a string, array, buffer
    or typed array. Where the language does not fault on that, the read returns
    undefined or the write lands somewhere nothing reads, which is harder to
    notice rather than safer.
  false: Nothing in `method` does this.
  issue:
    type: defect
    label: self
  min: 70

- name: use_after_free
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    Something already closed, aborted, destroyed or released is used again, or
    released twice. A stream written after it ended, a handle read after close,
    a controller used after abort, a connection used after it went back to the
    pool.
  false: Nothing in `method` does this.
  issue:
    type: defect
    label: self
  min: 70

- name: uninitialized_use
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    A value is read before anything has written it, so what comes back is
    undefined where a value was meant to be. A field never set, a binding read
    before its declaration runs, or a result used before the work that produces
    it has finished.
  false: Nothing in `method` does this.
  issue:
    type: defect
    label: self
  min: 70

- name: integer_overflow
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    Arithmetic can wrap, truncate, or change sign, and the result is then used
    as a size, an index, a length, or a permission
  false: Nothing in `method` does this.
  issue:
    type: defect
    label: self
  min: 70

- name: race_condition
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    Two paths can reach the same state at once without holding anything, or a
    check and the act it guards are separated in a way another path can exploit
  false: Nothing in `method` does this.
  issue:
    type: defect
    label: self
  min: 70

- name: type_confusion
  each: method
  where: "**/*"
  ask: Is this true of `method`?
  true: >-
    A value is treated as a type, shape, or variant it may not be: an unchecked
    cast, a union read through the wrong member, a parsed object trusted to have
    a shape
  false: Nothing in `method` does this.
  issue:
    type: defect
    label: self
  min: 70