Rule_options.atd

(* Semgrep matching engine configuration.

   The goal of this module is to gather in one place all the possible
   ways to configure the semgrep matching engine. We now let
   the user enable/disable certain features on a per-rule (could do even
   per-pattern basis?). For example, constant propagation may be too powerful
   sometimes and prevent people to find certain code.
   Those features are called 'options' in the rule.

   Note that each option in this file will change the matching results;
   for non-functional settings such as optimizations (e.g., using a
   cache) use instead Flag_semgrep.ml

   We're using atdgen to specify the list of configuaration options
   because atdgen generates automatically the boilerplate to read
   the configuration options from a rule file.

   TODO: before this can work with Python, all the custom default field values
         must be specified for Python as well. The same must be done
         for any target language that we want to support.
         A better way would be to modify atd to handle this better.
         Ideas for improvements include:
         - make 'atdpy --no-implicit-defaults' treat '~field: bool'
           as '?field: bool option' unless a default value is set for
           Python with an annotation like '<python default="True">'.
         - make atd understand a syntax for default values that can be
           used to specify defaults in all target languages.
           A default value would be set with '<field default="true">'
           and this would be translated into 'True' for Python and whatever
           means "true" in other languages.

   coupling: with semgrep-interfaces/rule_schema_v2.atd
*)

(* !!Do not rename the fields because they can be referenced in rules!! *)
type t = {
  ~constant_propagation <ocaml default="true"> : bool;
  (* symbolic_propagation requires constant_propagation to have effect *)
  ~symbolic_propagation <ocaml default="false"> : bool;

  (* metavariables common to a source and sink will be unified *)
  ~taint_match_on <ocaml default="`Sink">: taint_match_on;
  ~taint_unify_mvars <ocaml default="false"> : bool;
  ~taint_assume_safe_functions <ocaml default="false"> : bool;
  ~taint_assume_safe_indexes <ocaml default="false"> : bool;
  ~taint_assume_safe_comparisons <ocaml default="false"> : bool;
  ~taint_assume_safe_booleans <ocaml default="false"> : bool;
  ~taint_assume_safe_numbers <ocaml default="false"> : bool;
  (* when you are paranoid about minimizing FPs, and probably useful for
   * writing secret detection rules *)
  ~taint_only_propagate_through_assignments <ocaml default="false"> : bool;

  (* 'ac' stands for associative-commutative matching *)
  ~ac_matching <ocaml default="true"> : bool;
  (* pretend && and || are commutative *)
  (* THINK: Should we merge ac_matching and commutative_boolop into a single setting? *)
  ~commutative_boolop <ocaml default="false"> : bool;
  (* DEPRECATED: remove me after 1.60.0 *)
  ~commutative_compop <ocaml default="false"> : bool;
  ~symmetric_eq <ocaml default="false"> : bool;

  (* assign-patterns (e.g. `$X = $E`) will match var-defs (e.g. `var x = 1;`) *)
  ~vardef_assign <ocaml default="true"> : bool;
  (* assign-patterns (e.g. `$X = function() { ... }`) will match fld-defs
   * (e.g. `class Foo {  x = function() { return; } }`).
   *)
  ~flddef_assign <ocaml default="false"> : bool;
  (* expression patterns (e.g. `f($X)`) will match attributes (e.g. `@f(a)`)  *)
  ~attr_expr <ocaml default="true"> : bool;

  (* treat arrows (a.k.a short lambdas) like other functions *)
  ~arrow_is_function <ocaml default="true">: bool;
  (* treat let/const as equivalent to var (JS-specific) *)
  ~let_is_var <ocaml default="true">: bool;

  (* !experimental: a bit hacky, and may introduce big perf regressions! *)
  (* should be used with DeepEllipsis; do it implicitely has issues *)
  ~go_deeper_expr <ocaml default="true"> : bool;
  (* this ultimately should go away once '...' works on the CFG *)
  ~go_deeper_stmt <ocaml default="true"> : bool;

  (* implicitly assume deep ellipsis in expression statement *)
  (* TODO: eventually the default should be 'false'. *)
  ~implicit_deep_exprstmt <ocaml default="true"> : bool;

  (* implicitly assume ellipsis in record patterns *)
  (* TODO: eventually the default should be 'false'. *)
  ~implicit_ellipsis <ocaml default="true"> : bool;

  (* let `<foo />` singleton also match `<foo></foo>` *)
  ~xml_singleton_loose_matching <ocaml default="true"> : bool;
  (* implicitly assume ellipsis in xml attributes *)
  (* TODO: eventually the default should be 'false'. *)
  ~xml_attrs_implicit_ellipsis <ocaml default="true"> : bool;
  (* if false, xml children are matched in any order *)
  ~xml_children_ordered <ocaml default="true"> : bool;

  ~generic_engine <ocaml default="`Spacegrep">: generic_engine;

  ~cpp_parsing_pref <ocaml default="`AsVarDefWithCtor">: cpp_parsing_opt;

  (* Enable/disable multiline mode in aliengrep. This option is only
     relevant to the 'aliengrep' generic engine.

     The line mode differs from the default multiline mode in
     these aspects:
     - Regular ellipses ('...' or '$...FOO') don't match newlines.
     - Long ellipses using four dots ('....' or '$....FOO') must be used
       to match newlines.
     - Newlines in patterns must match newlines in the target code.
     - Double quotes and single quotes are treated as additional brace
       pairs by default (see 'generic_braces').
  *)
  ~generic_multiline
    <ocaml default="true">
    <python default="True">: bool;

  (* The list of matching braces to be considered by the aliengrep engine.
     The default braces in the default, multiline mode are:
     - parentheses;
     - square brackets;
     - curly braces.

     = ["(", ")"], ["[", "]"], ["{", "}"]

     The default braces in the line mode are:
     - all the braces valid in multline mode;
     - double quotes;
     - single quotes.

     = ["(", ")"], ["[", "]"], ["{", "}"], ["\"", "\""], ["'", "'"]
  *)
  ?generic_braces: (string * string) list option;

  (* This option extends the set of braces instead of
     replacing it like 'generic_braces' does. *)
  ~generic_extra_braces: (string * string) list;

  (* Extra characters allowed in a so-called word when using the aliengrep
     engine. A word is a sequence of characters that can be captured by
     a metavariable. By default, a word follows the pattern [A-Za-z0-9_]+.
     It may not be a substring of a longer word.
     This option adds word characters. For example, the list ["-"] adds
     a dash to the word characters, allowing '$FOO' to match 'e-mail'. *)
  ~generic_extra_word_characters: string list;

  (* Perform case-insensitive matching according to Unicode rules.
     The default is false.
     This is supported only by the aliengrep engine.
     Back-references, however, must still respect the case of the first
     match e.g. "$A $A" matches "Hello Hello" but not "Hello hello". *)
  ~generic_caseless: bool;

  (* Maximum number of newlines that an ellipsis can match with the spacegrep
     engine. Use 0 to contain the match within a single line. *)
  ~generic_ellipsis_max_span <ocaml default="10">: int;

  (* Preprocess comments away to facilitate matching with spacegrep. *)
  ?generic_comment_style: generic_comment_style option;

  (* Whether a rule should be considered for interfile analysis. *)
  ~interfile <ocaml default="false"> : bool;

  (* Whether last expression executed in a function is treated the
     same as a return statement. This option is specific only to
     languages that treat the last statement of a block inside
     functions as a return statement, such as Ruby and Julia.  *)
     ~implicit_return <ocaml default="true"> : bool;

  (* TODO: equivalences:
   *   - require_to_import (but need pass config to Js_to_generic)
   *)
}

type cpp_parsing_opt = [
  | AsFunDef <json name="as_fundef">
  | AsVarDefWithCtor <json name="as_vardef_with_ctor">
]

type generic_engine = [
  | Aliengrep <json name="aliengrep">
  | Spacegrep <json name="spacegrep"> (* default, legacy *)
]

type generic_comment_style = [
  | C <json name="c"> (* /* ... */ *)
  | Cpp <json name="cpp"> (* /* ... */ or // ... *)
  | Shell <json name="shell"> (* # ... *)
]

type taint_match_on = [
  | Source <json name="source">
  | Sink <json name="sink"> (* default *)
]