Example TTPs: Command-Line Arguments (#436)

Summary:
Pull Request resolved: #436

* Provide examples for a variety of command-line argument configurations
* Will link this in documentation after they land
* Refine regexp handling in arguments so that it is a bit more flexible

Reviewed By: nicolagiacchetta

Differential Revision: D51459399

fbshipit-source-id: 6428f6f2f1d4ee0e8a81dccc9348a46f6cfd5198

example-ttps/args/basic.yaml

@@ -0,0 +1,33 @@
+---
+name: Basic Command-Line Arguments
+description: |
+  TTPForge allows users to configure their TTPs' expected command-line
+  arguments in various ways. This TTP demonstrates the following
+  basic command-line argument options:
+    * Support for Various Argument Types (string, int, bool, etc)
+    * Default Values for Arguments
+args:
+  - name: str_to_print
+    description: this argument is of the default type `string`
+  - name: has_a_default_value
+    description: |
+      the default value will be used if the user does not explicitly
+      specify a value
+    default: this_is_the_default
+  - name: run_second_step
+    type: bool
+    default: false
+  - name: int_arg
+    type: int
+    default: 1337
+steps:
+  - name: first_Step
+    print_str: |
+      Value of argument `str_to_print`: {{.Args.str_to_print}}
+      Value of argument `has_a_default_value`: {{.Args.has_a_default_value}}
+  {{ if .Args.run_second_step }}
+  - name: second_step
+    print_str: |
+      You must have passed `--run_second_step=true`
+      Doing some math : {{add .Args.int_arg 5}}
+  {{ end }}

example-ttps/args/choices.yaml

@@ -0,0 +1,29 @@
+---
+name: Explicitly Allowed Choices for Command-Line Arguments
+description: |
+  Sometimes, you might need a TTP to only accept
+  certain specific values of a given command-line argument.
+  The `choices:` field of the argument spec format provides
+  you with this capability.
+args:
+  - name: arg_with_choices
+    descriptions: you must pass one of these values in order to avoid an error
+    choices:
+      - A
+      - B
+      - C
+  - name: with_default
+    type: int
+    descriptions: |
+      arguments with `choices` can have default values to,
+      but the default value must be one of the choices.
+    choices:
+      - 1
+      - 2
+      - 3
+    default: 3
+steps:
+  - name: first_Step
+    print_str: "You must have selected a valid choice: {{.Args.arg_with_choices}}"
+  - name: second_step
+    print_str: "Value for argument `with_default`: {{.Args.with_default}}"

example-ttps/args/regexp.yaml

@@ -0,0 +1,20 @@
+---
+name: Regular Expression Validation for Command-Line Arguments
+description: |
+  You can require user-provided command-line arguments
+  to match a provided regular expression.
+  Golang regexp syntax documentation: https://pkg.go.dev/regexp/syntax
+  NOTE: `regexp` is only supported for arguments of type `string` (the default)
+args:
+  - name: must_contain_ab
+    descriptions: requirement satisfied if `ab` occurs anywhere in the string
+    regexp: ab
+  - name: must_start_with_1_end_with_7
+    type: string
+    description: requirement satisfied if argument starts with `1` and ends with `7`
+    regexp: ^1.*7$
+steps:
+  - name: valid_args_provided
+    print_str: |
+      Valid value for arg `must_contain_ab`: {{.Args.must_contain_ab}}
+      Valid value for arg `must_start_with_1_end_with_9`: {{.Args.must_start_with_1_end_with_7}}

pkg/args/regexp.go

@@ -0,0 +1,29 @@
+/*
+Copyright © 2023-present, Meta Platforms, Inc. and affiliates
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+package args
+
+import "fmt"
+
+func verifyCanUseWithRegexp(spec Spec) error {
+	if spec.Type == "" || spec.Type == "string" {
+		return nil
+	}
+	return fmt.Errorf("`regexp:` can only be used with string arguments")
+}

pkg/args/spec.go

@@ -83,14 +83,8 @@ func ParseAndValidate(specs []Spec, argsKvStrs []string) (map[string]any, error)
 		// append and prepend if missing
 		// if Format string is missing ^$ then we are subject to partial matches
 		if spec.Format != "" {
-			if spec.Type != "string" {
-				return nil, fmt.Errorf("`regexp:` can only be used with string arguments")
-			}
-			if spec.Format[0] != '^' {
-				spec.Format = "^" + spec.Format
-			}
-			if spec.Format[len(spec.Format)-1] != '$' {
-				spec.Format = spec.Format + "$"
+			if err := verifyCanUseWithRegexp(spec); err != nil {
+				return nil, err
 			}
 			spec.formatReg, err = regexp.Compile(spec.Format)
 			if err != nil {

pkg/args/spec_test.go

@@ -220,16 +220,48 @@ func TestValidateArgs(t *testing.T) {
 			wantError: false,
 		},
 		{
-			name: "Format with invalid value",
+			name: "Format (Flexible Match; No Error)",
 			specs: []Spec{
 				{
 					Name:   "alpha",
 					Type:   "string",
-					Format: "[A-Z_]+",
+					Format: "ab",
+				},
+			},
+			argKvStrs: []string{
+				"alpha=xabyabz",
+			},
+			expectedResult: map[string]any{
+				"alpha": "xabyabz",
+			},
+		},
+		{
+			name: "Format (Strict Match; No Error)",
+			specs: []Spec{
+				{
+					Name:   "alpha",
+					Type:   "string",
+					Format: "^ab$",
+				},
+			},
+			argKvStrs: []string{
+				"alpha=ab",
+			},
+			expectedResult: map[string]any{
+				"alpha": "ab",
+			},
+		},
+		{
+			name: "Format (Strict Match; Error)",
+			specs: []Spec{
+				{
+					Name:   "alpha",
+					Type:   "string",
+					Format: "^ab$",
 				},
 			},
 			argKvStrs: []string{
-				"alpha=INVALID_CECI_NEST_PAS-",
+				"alpha=xaby",
 			},
 			wantError: true,
 		},