feat(cli): Add -i / --instruction flag and enhance parameter parsing

Author: vishnurajkv

README.md

@@ -115,20 +115,37 @@ secnodeapi --target http://api.local/spec --mode agent --request-budget 500 --ma
 ```
 
 ### Full CLI Options
-| Option | Description |
-|---|---|
-| `--target` | URL or local path to OpenAPI schema (required) |
-| `--mode` | `agent` (default) or `legacy` execution pipeline |
-| `--concurrency` | Concurrent request workers |
-| `--auth-header` | Single inline auth header |
-| `--auth-file` | JSON file of auth headers |
-| `--identities-file` | JSON identities for differential auth testing |
-| `--schema-only` | Output normalized API structure and exit |
-| `--dry-run` | Generate tests without executing |
-| `--request-budget` | Max request count in agent mode |
-| `--max-iterations` | Max plan/execute loops in agent mode |
-| `--proxy` | Route traffic via proxy |
-| `--insecure` | Disable TLS verification |
+### Options
+
+| Flag | Description | Default |
+| :--- | :--- | :--- |
+| `--target` | URL or local path to OpenAPI schema (required) | `None` |
+| `--mode` | `agent` (default) or `legacy` execution pipeline | `agent` |
+| `-i`, `--instruction` | Pass parameters (key=value) for AI test generation | `None` |
+| `--concurrency` | Number of parallel requests | `5` |
+| `--auth-header` | Inline auth header (e.g., `Authorization: Bearer 123`) | `None` |
+| `--auth-file` | JSON file of auth headers | `None` |
+| `--identities-file` | JSON identities for differential auth testing | `None` |
+| `--schema-only` | Output normalized API structure and exit | `False` |
+| `--dry-run` | Generate tests without executing | `False` |
+| `--request-budget` | Max requests for the entire agent run | `400` |
+| `--max-iterations` | Max plan/execute loops in agent mode | `5` |
+| `--proxy` | Route traffic through an HTTP proxy | `None` |
+| `--insecure` | Disable TLS verification | `False` |
+
+### User Instructions (`-i`)
+
+The `-i` flag allows you to provide the agent with specific data points (tokens, usernames, IDs) to make its adversarial reasoning more realistic. You can use space or comma-separated pairs:
+
+```bash
+# Using the -i flag
+docker run --rm secnodeapi -i "username=admin token=jasdndsfnfdsng" --target ...
+```
+
+The agent will:
+1.  **Parse** these values during the Buildup Phase.
+2.  **Inject** them into its AI world-model for understanding the API.
+3.  **Prioritize** them when generating test cases (e.g., using the provided token for BOLA/BFLA attempts).
 
 ## Docker Support
 

src/secnodeapi/cli.py

@@ -98,10 +98,11 @@ def parse_identities(identities_file: str) -> List[IdentityContext]:
 
 
 def parse_instructions(args) -> List[InstructionSet]:
-    """Parse instruction sets from CLI arguments --instruction1 through --instruction5.
+    """Parse instruction sets from CLI arguments -i/--instruction and --instruction1 through --instruction5.
     
-    Each argument should be comma-separated key=value pairs, e.g.:
-    --instruction1 "token=xxx, username=vishn, password=secret123"
+    Arguments can be comma or space separated key=value pairs, e.g.:
+    -i "token=xxx username=vishn"
+    --instruction1 "token=xxx, password=secret123"
     
     Args:
         args: argparse Namespace
@@ -111,36 +112,50 @@ def parse_instructions(args) -> List[InstructionSet]:
     """
     instructions: List[InstructionSet] = []
 
+    # Check new -i/--instruction flag first
+    main_instr = getattr(args, "instruction", None)
+    if main_instr and isinstance(main_instr, str):
+        variables = _parse_kv_string(main_instr)
+        if variables:
+            instructions.append(InstructionSet(name="cli_instruction", variables=variables))
+    
+    # Check legacy numbered flags
     for i in range(1, 6):
         arg_name = f"instruction{i}"
         value = getattr(args, arg_name, None)
 
         if not value or not isinstance(value, str):
             continue
 
-        # Parse comma-separated key=value pairs
-        variables: Dict[str, str] = {}
-        pairs = value.split(",")
-        
-        for pair in pairs:
-            pair = pair.strip()
-            if "=" not in pair:
-                continue
-                
-            # Split on first = only, so values can contain =
-            key, val = pair.split("=", 1)
-            key = key.strip()
-            val = val.strip()
-            
-            if key:  # Only add non-empty keys
-                variables[key] = val
-        
+        variables = _parse_kv_string(value)
         if variables:
             instructions.append(InstructionSet(name=arg_name, variables=variables))
 
     return instructions
 
 
+def _parse_kv_string(value: str) -> Dict[str, str]:
+    """Parse a string of key=value pairs separated by commas or spaces."""
+    variables: Dict[str, str] = {}
+    
+    # Replace commas with spaces to handle both delimeters uniformly
+    normalized = value.replace(",", " ")
+    # Use split() to handle multiple spaces
+    pairs = normalized.split()
+    
+    for pair in pairs:
+        if "=" not in pair:
+            continue
+            
+        key, val = pair.split("=", 1)
+        key = key.strip()
+        val = val.strip()
+        
+        if key:
+            variables[key] = val
+    return variables
+
+
 def parse_vars(vars_list: List[str]) -> Dict[str, str]:
     """Parse --var arguments into a dictionary.
     
@@ -208,6 +223,10 @@ def parse_args():
         action="store_true",
         help="Generate tests but do not execute",
     )
+    parser.add_argument(
+        "--instruction", "-i",
+        help="Main instruction set (key=value pairs, space or comma separated)",
+    )
     parser.add_argument(
         "--dry-run-output",
         help="Write generated tests to JSON file (use with --dry-run)",

src/secnodeapi/services/pipeline.py

@@ -378,6 +378,10 @@ async def build_pipeline_artifacts(
     pipeline_input: PipelineInput,
 ) -> tuple:
     """Run schema load, active recon, tool orchestration, understanding, and test generation."""
+    if pipeline_input.instructions:
+        for instr in pipeline_input.instructions:
+            console.print(f"[dim]📝 User instructions loaded ({instr.name}):[/] [cyan]{instr.variables}[/]")
+            
     raw_schema = await fetch_schema(
         pipeline_input.target,
         proxy=pipeline_input.proxy,

src/secnodeapi/services/tool_orchestrator.py

@@ -177,6 +177,12 @@ async def run_tool_orchestration_phase(
 
     console.rule("[bold blue]Phase 1b: Tool Orchestration")
     logger.info("Starting AI-driven tool orchestration phase")
+    
+    if pipeline_input.instructions:
+        for instr in pipeline_input.instructions:
+            console.print(f"[dim]📝 User instructions loaded ({instr.name}):[/] [cyan]{instr.variables}[/]")
+
+    api_structure, seed_tests, orch_result = await build_pipeline_artifacts(pipeline_input)
 
     # 1. Get AI tool plan
     console.print("[dim]🤖 Asking AI to plan tool invocations...[/]")