interfaces/Rule_options.atd
Rama main · réplica de lectura del repositorio original.
(* 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 configuration 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 is DEPRECATED and to be removed after 1.63.0 *)
~taint_match_on <ocaml default="`Sink">: taint_match_on;
~taint_focus_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;
(* enable intra-file inter-procedural taint analysis *)
~taint_intrafile <ocaml default="false"> : bool;
(* attach branch-condition guards to taint effects and evaluate them at
* call sites (experimental). When off, only Clojure keeps the
* [length(x) == n] arity guards that implement multi-arity dispatch.
* The user-visible rule option is [guarded_taint_signatures]; the
* internal field name stays [effect_guards]. *)
~effect_guards <json name="guarded_taint_signatures"> <ocaml default="false"> : bool;
(* enable cross-file taint analysis via the in-process project call graph *)
~taint_interfile <ocaml default="false"> : bool;
(* maximum call chain depth for companion file discovery; negative is
* unbounded; unset defers to the scan's value *)
?taint_interfile_depth : int option;
(* '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;
~unify_ids_strictly <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.
Alias for taint_interfile, the name published rules use; it sets
taint_interfile when the rule is parsed, and setting both is an error. *)
~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;
(* non-keyword attributes such as decorators in Python will be matched in order
* instead of the default order-agnostic matching. keyword attributes, such as
* inline, static, etc, are not affected by this option
*)
~decorators_order_matters <ocaml default="false"> : bool;
(* restrict the number of matches to report on a rule. *)
?max_match_per_file : int option;
(* override the default taint fixpoint timeout. *)
?taint_fixpoint_timeout : float option;
(* rule-specific timeout. *)
?timeout : float option;
(* adjust timeout according to target file size. *)
?dynamic_timeout : bool option;
(* unit for dynamic timeout calculation: roughly, how many
times 30kb is the target file, clamped to be between 1.
and [dynamic_timeout_max_multiplier]. *)
?dynamic_timeout_unit_kb : int option;
(* limit for dynamic timeout factor, to place a boundary on timeouts
for very large files. *)
?dynamic_timeout_max_multiplier : int option;
(* 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 *)
]