adds command to recipes, removes the default command hack (#1027)

* adds `command` to recipes, removes the default command hack

After the introduction of the commands in bap, the recipe system wasn't updated and it was only possible to write recipes for the default `disassemble` command. We use recipes to pack our analysis into self-contained entities and we would like to be benefit from commands, e.g., we would like to be able to implement analyses that do not require a fully disassembly of the target file.

This PR adds the `command' stanza to the recipe grammar. The new command stanza didn't play well with the hack that was prepending the `disassemble` command when the first argument was a file. No worries, the command is still optional, we were just able to find a much better solution, which is not a hack. Now it is the responsiblility of `Bap_main.init` to set the default command if no command was specified. So no more hacks, no need for `:` to disambiguate command and, more importantly, no need to specify the file before any other arguments on the command line, which was previously required by the hack.

To summarize, if no command is specified then `disassemble` is the default command. A recipe may specify a command, it will be prepended in the right position. Users may specify a command on the command like if they want to.

For example, consider a recipe (named `mc-test`) with the following specification
```
(command mc)
(option llvm-x86-syntax intel)
(option show-insn asm)
(option show-bil)
```

The following are valid invocations of this recipe,

```
bap 48 83 ec 08 --recipe=mc-test    # the command could be omitted
bap mc 48 83 ec 08 --recipe=mc-test # can specify the command
bap --recipe=mc-test -- 48 83 ec 08 # recipes now work fine with --
```

* updates the testsuite to reflect the changed command syntax

Author: ivg

lib/bap_main/bap_main.ml

@@ -598,8 +598,9 @@ module Grammar : sig
     ?env:(string -> string option) ->
     ?help:Format.formatter ->
     ?default:(ctxt -> (unit,Error.t) Result.t) ->
+    ?command:string ->
     ?err:Format.formatter ->
-    ?argv:string array -> unit -> (unit, Error.t) Result.t
+    string array -> (unit, Error.t) Result.t
 end = struct
   open Cmdliner
 
@@ -983,7 +984,7 @@ end = struct
         Term.(const serve_manpage $ served $ make_help_option plugin))
 
   let eval ?(man="") ?(name=progname) ?version ?env
-      ?(help=Format.std_formatter) ?default ?err ?argv () =
+      ?(help=Format.std_formatter) ?default ?command ?err argv =
     let plugin_names = Plugins.list () |> List.map ~f:Plugin.name in
     let disabled_plugins = no_plugin_options plugin_names in
     let plugin_options = concat_plugins () in
@@ -1003,7 +1004,16 @@ end = struct
       | Some f -> Term.(const (fun p -> match p with
           | Error _ as err -> err
           | Ok () -> f @@ Context.request ()) $ plugins) in
-    match Term.eval_choice ~catch:false ?env ~help ?err ?argv
+    let argv = match command with
+      | None -> argv
+      | Some cmd -> match Array.to_list argv with
+        | prog :: arg :: rest ->
+          if List.exists commands ~f:(fun (_,info) ->
+              String.is_prefix ~prefix:arg (Term.name info))
+          then argv
+          else Array.of_list (prog::cmd::arg::rest)
+        | [_] | [] -> argv in
+    match Term.eval_choice ~catch:false ?env ~help ?err ~argv
             (main,main_info) commands with
     | `Ok (Ok ()) -> Ok ()
     | `Ok (Error _ as err) -> err
@@ -1124,6 +1134,7 @@ let init
     ?env ?log ?out ?err ?man
     ?name ?(version=Bap_main_config.version)
     ?default
+    ?default_command
     () =
   match state.contents with
   | Loaded _ -> Error Error.Already_initialized
@@ -1134,7 +1145,7 @@ let init
       | None | Some None -> Ok argv
       | Some (Some spec) ->
         load_recipe spec >>= fun spec ->
-        Ok (Array.append argv @@ Bap_recipe.argv spec) in
+        Ok (Bap_recipe.argv ~argv spec) in
     argv >>= fun argv ->
     let log = match log with
       | Some _ -> log
@@ -1152,9 +1163,9 @@ let init
           | Ok p -> `Fst p
           | Error (p,e) -> `Snd (p,e)) in
     if List.is_empty failures
-    then match
-        Grammar.eval ?name ~version ?env ?help:out
-          ?err ?man ~ argv ?default ()
+    then match Grammar.eval argv
+                 ?name ~version ?env ?help:out
+                 ?err ?man ?default ?command:default_command
       with
       | Ok () ->
         state := Loaded plugins;

lib/bap_main/bap_main.mli

@@ -438,7 +438,11 @@ type ctxt
     @parameter version defaults to the BAP Framework version.
 
     @parameter default, if specified, then this function will be invoked
-    when no command was specified in the command line.
+    when no command line arguments were provided.
+
+    @parameter default_command, if specified, then this command will
+    be used when command line arguments are provided but do not
+    specify a command. @since 2.1.0.
 *)
 val init :
   ?features:string list ->
@@ -453,6 +457,7 @@ val init :
   ?name:string ->
   ?version:string ->
   ?default:(ctxt -> (unit,error) result) ->
+  ?default_command:string ->
   unit -> (unit, error) result
 
 

lib/bap_recipe/bap_recipe.ml

@@ -33,11 +33,13 @@ type param = {
 }
 
 type item =
+  | Cmd of string
   | Use of string
   | Opt of string * string list
   | Par of param
 
 type spec = {
+  cmd : string option;
   uses : string list;
   opts : (string * string list) list;
   pars : param list;
@@ -65,6 +67,7 @@ type t = {
 }
 
 let empty_spec = {
+  cmd = None;
   uses = [];
   opts = [];
   pars = [];
@@ -89,6 +92,7 @@ let item_of_sexp = function
     atoms args >>| fun args -> Opt (name, args)
   | Sexp.List (Sexp.Atom "parameter" :: Sexp.Atom s :: _) ->
     Error (Bad_param s)
+  | Sexp.List [Sexp.Atom "command";  Sexp.Atom name] -> Ok (Cmd name)
   | x -> Error (Bad_item x)
 
 
@@ -97,7 +101,8 @@ let items_of_sexps xs = Result.all (List.map xs ~f:item_of_sexp)
 let spec_of_items = List.fold ~init:empty_spec ~f:(fun spec -> function
     | Use x -> {spec with uses = x :: spec.uses}
     | Opt (x,xs) -> {spec with opts = (x,xs) :: spec.opts}
-    | Par x -> {spec with pars = x :: spec.pars})
+    | Par x -> {spec with pars = x :: spec.pars}
+    | Cmd name -> {spec with cmd = Some name})
 
 let (/) = Filename.concat
 
@@ -264,7 +269,28 @@ let load ?paths ?env name =
 let rec args t =
   List.concat_map t.loads ~f:args @ t.args
 
-let argv t = Array.of_list @@ args t
+let prepend_before_dash_dash argv args =
+  match Array.findi argv ~f:(fun _ -> String.equal "--") with
+  | None -> Array.append argv args
+  | Some (p,_) -> Array.concat [
+      Array.subo ~len:p argv;
+      args;
+      Array.subo ~pos:p argv
+    ]
+
+let args t = Array.of_list @@ args t
+let command t = t.spec.cmd
+let argv ?(argv=[||]) t = match command t with
+  | None -> prepend_before_dash_dash argv (args t)
+  | Some cmd ->
+    let argv = Array.of_list @@ match Array.to_list argv with
+    | [] | [_] as argv -> argv @ [cmd]
+    | self :: arg :: rest when String.is_prefix ~prefix:arg cmd ->
+      self :: cmd :: rest
+    | self :: arg :: rest ->
+      self :: cmd :: arg :: rest in
+    prepend_before_dash_dash argv (args t)
+
 
 let rec params t = t.spec.pars @ List.concat_map t.loads ~f:params
 

lib/bap_recipe/bap_recipe.mli

@@ -3,6 +3,25 @@ type error
 type t
 type param
 
+
+
+(** [load recipe] searches and loads a recipe.
+
+    Searches a recipe in the search paths specified with the [paths]
+    parameter, see the {!search} function for the description of the
+    search rules.
+
+    If a recipe is found then it is loaded. All recipes included in
+    the found recipe are also loaded with the [load] function using
+    the same [paths] and [env] arguments.
+
+    During the loading recipe parameters are substituted using the
+    [env] mapping.
+
+    If a recipe includes files, they are unpacked into a separate
+    folder, which will be removed when {!close} is called on the
+    recipe.
+  *)
 val load :
   ?paths:string list ->
   ?env:(string * string) list ->
@@ -17,18 +36,57 @@ val load :
 *)
 val search : string list -> string list
 
-(** [argv recipe] returns the argument vector for recipe.*)
-val argv : t -> string array
+
+(** [args recipe] is an array of arguments specified in the recipe. *)
+val args : t -> string array
+
+
+(** [command recipe] returns the [recipe] command, if one exists.  *)
+val command : t -> string option
+
+(** [argv recipe] builds an argument vector from the [recipe].
+
+    All arguments are appended to the passed [argv] (which defaults to
+    an empty array, not [Sys.argv]). If [argv] contains [--] then
+    arguments are prepended before [--] with everything after [--]
+    left intact.
+
+    If the [recipe] specifies a command then it is inserted after the
+    first argument in [argv] (if such exists), unless the second
+    argument already specifies the same command, in which case it is
+    ignored.
+*)
+val argv : ?argv:string array -> t -> string array
+
+
+(** [close recipe] closes the recipe and clears all associated resources.  *)
 val close : t -> unit
+
+
+(** [doc recipe] is the recipe description.  *)
 val doc : t -> string
+
+
+(** [params recipe] is the list of recipe parameters. *)
 val params : t -> param list
-val pp_error : Format.formatter -> error -> unit
 
 
+(** [pp_error ppf err] prints the error message [err].   *)
+val pp_error : Format.formatter -> error -> unit
+
+(** Recipe Parameters.  *)
 module Param : sig
   type t = param
+
+  (** [name p] the parameter [p] name.  *)
   val name : param -> string
+
+  (** [doc p] the parameter [p] description.  *)
   val doc : param -> string
+
+  (** [default p] the default value of the parameter [p].  *)
   val default : param -> string
+
+  (** [pp ppf p] prints the human-readable description of [p].  *)
   val pp : Format.formatter -> param -> unit
 end

plugins/recipe_command/recipe_command_main.ml

@@ -53,7 +53,7 @@ in parameter called $(b,prefix), that is substituted with the path
 to the recipe top folder. See the $(b,parameter) command to learn
 how to introduce parameters.
 
-The parameter command introduces a parameter to the recipe, i.e.,
+The $(b,parameter) command introduces a parameter to the recipe, i.e.,
 a variable ingredient that could be changed when the recipe is
 used. The parameter command has 3 arguments, all required. The
 first argument is the parameter name, the second is the default
@@ -71,6 +71,11 @@ If the parameter is not set through the command line, then it will
 be substituted with $(b,128) otherwise it will receive whatever
 value a user has passed.
 
+The $(b,command) stanza specifies the command that the recipe should
+run. It is optional, since recipes could be generic and applicable to
+different commands, which gives an extra freedom to the recipe
+user.
+
 Finally, the $(b,extend) command is like the include statement in
 the C preprocessor as it includes all the ingredients from another
 recipe. (Make sure that you're not introducing loops!). The
@@ -81,10 +86,11 @@ include.;
 
 ```
     recipe ::= {<recipe-item>}
-    recipe-item ::= <option> | <parameter> | <extend>
+    recipe-item ::= <option> | <parameter> | <extend> | <command>
     option ::= (option <atom> {<atom>})
     parameter ::= (parameter <atom> <atom> <atom>)
     extend ::= (extend <atom>)
+    command ::= (command <atom>)
 ```
 |}
 

src/bap_frontend.ml

@@ -30,29 +30,6 @@ open Bap_main.Extension
 
 module type unit = sig end
 
-let qualified cmd =
-  if String.length cmd > 2 && Char.equal cmd.[0] ':'
-  then Some (String.subo ~pos:1 cmd)
-  else None
-
-let is_option = String.is_prefix ~prefix:"-"
-
-(* To preserve backward compatibility and enhance usability we
-   automatically add the `disassemble' command if the first argument is
-   a file. However, since we can have a potential clash between a
-   command name, a command name could be prefixed with `:`, so that
-   it will be interpreter literally as a keyword, not as a file.
-*)
-let autocorrect_input args =
-  Array.of_list @@ match Array.to_list args with
-  | [] | [_] as args -> args
-  | name :: arg :: args as input ->
-    if is_option arg then input else match qualified arg with
-      | Some cmd -> name::cmd::args
-      | None ->
-        if Sys.file_exists arg && not (Sys.is_directory arg)
-        then name :: "disassemble" :: arg :: args
-        else name :: arg :: args
 
 let pp_info ppf infos =
   List.iter infos ~f:(fun info ->
@@ -81,10 +58,13 @@ Commands:
 Plugins:
 %a
 
-If no command is specified and the first parameter is a file,
-then the `disassemble' command is assumed. If the name of a
-command conflicts with an existing file, prefix the name with
-`:', e.g., `bap :plugins'.
+If no command line options or arguments are specified, then this
+message is printed. To hush this message specify the `.' command,
+e.g., `bap .'. The command could be omitted altogether, in that case the
+`disassemble' command is assumed, e.g., `bap /bin/ls' is the same
+as `bap disassemble /bin/ls'. Not that the default command is
+subject to change, so it is better not to rely on this behavior in
+your automation tools.
 
 Run 'bap <COMMAND> --help' for more information a command.
 Run 'bap --<PLUGIN>-help for more information about a plugin.
@@ -296,14 +276,16 @@ let () =
 
 let () =
   let _unused : (module unit) = (module Bap.Std) in
-  let argv = autocorrect_input Sys.argv in
   let () =
     try if Sys.getenv "BAP_DEBUG" <> "0" then
         Printexc.record_backtrace true
     with Caml.Not_found -> () in
   Sys.(set_signal sigint (Signal_handle exit));
   at_exit Format.(pp_print_flush err_formatter);
-  match Bap_main.init ~default:print_info ~name:"bap" ~man ~argv () with
+  match Bap_main.init ~default:print_info
+          ~default_command:"disassemble"
+          ~name:"bap" ~man ~argv:Sys.argv ()
+  with
   | Ok () -> ()
   | Error (Error.Exit_requested code) -> exit code
   | Error Error.Configuration -> exit 1