feat: add skip() function and fuzzy module exclusion support

- Add skip() function to terminate remaining steps in current module while continuing to next module, with optional message parameter
- Implement isFuzzyModuleExcluded() for substring-based module filtering in ExecuteFlow
- Add fuzzy_exclude_modules CLI flag (-X) to both run and scan commands for flexible module exclusion
- Handle ErrSkipModule sentinel error throughout executor (executeStep, executeStepsDAG, ExecuteModule, ExecuteFlow) with proper status propagation
- Update function registry and Goja runtime to register skip() function
- Add comprehensive unit tests for skip() behavior, SkipModuleError, and fuzzy module matching
- Update snapshot tests to use generic example.com instead of shopee.vn

Author: j3ssie

internal/executor/executor.go

@@ -568,6 +568,16 @@ func isModuleExcluded(moduleName string, excludeList []string) bool {
 	return false
 }
 
+// isFuzzyModuleExcluded checks if a module name contains any of the fuzzy exclude patterns
+func isFuzzyModuleExcluded(moduleName string, fuzzyList []string) bool {
+	for _, pattern := range fuzzyList {
+		if strings.Contains(moduleName, pattern) {
+			return true
+		}
+	}
+	return false
+}
+
 // formatDuration formats a duration in human-readable format
 func formatDuration(d time.Duration) string {
 	if d < time.Second {
@@ -1233,6 +1243,25 @@ func (e *Executor) ExecuteModule(ctx context.Context, module *core.Workflow, par
 			metrics.RecordStepDuration(string(step.Type), string(stepResult.Status), stepResult.Duration.Seconds())
 
 			if err != nil {
+				// Check if this is a skip-module signal
+				if errors.Is(err, functions.ErrSkipModule) {
+					msg := "skip() called"
+					var skipErr *functions.SkipModuleError
+					if errors.As(err, &skipErr) {
+						msg = skipErr.Message
+					}
+					execCtx.Logger.Info("Module skipped",
+						zap.String("step", step.Name),
+						zap.String("message", msg),
+					)
+					result.Status = core.RunStatusSkipped
+					result.Message = msg
+					result.Exports = execCtx.Exports
+					result.EndTime = time.Now()
+					metrics.RecordWorkflowEnd(module.Name, string(core.KindModule), string(result.Status), result.EndTime.Sub(result.StartTime).Seconds())
+					return result, nil
+				}
+
 				execCtx.Logger.Error("Step failed",
 					zap.String("step", step.Name),
 					zap.Error(err),
@@ -1475,6 +1504,21 @@ func (e *Executor) executeStepsDAG(ctx context.Context, steps []core.Step, execC
 			}
 
 			if err != nil {
+				// Check if this is a skip-module signal
+				if errors.Is(err, functions.ErrSkipModule) {
+					if firstError == nil {
+						firstError = err
+					}
+					// Mark all remaining steps as completed to break the main loop
+					for name := range stepMap {
+						if !executed[name] {
+							executed[name] = true
+							atomic.AddInt32(&completedCount, 1)
+						}
+					}
+					cond.Signal()
+					return
+				}
 				failed[sName] = true
 				if firstError == nil && !e.shouldContinueOnError(s) {
 					firstError = err
@@ -1502,6 +1546,18 @@ func (e *Executor) executeStepsDAG(ctx context.Context, steps []core.Step, execC
 	result.Steps = collector.Results()
 
 	if firstError != nil {
+		// Check if the error was a skip-module signal (not a failure)
+		if errors.Is(firstError, functions.ErrSkipModule) {
+			msg := "skip() called"
+			var skipErr *functions.SkipModuleError
+			if errors.As(firstError, &skipErr) {
+				msg = skipErr.Message
+			}
+			result.Status = core.RunStatusSkipped
+			result.Message = msg
+			result.EndTime = time.Now()
+			return nil
+		}
 		result.Status = core.RunStatusFailed
 		result.Error = firstError
 		result.EndTime = time.Now()
@@ -1762,6 +1818,7 @@ func (e *Executor) ExecuteFlow(ctx context.Context, flow *core.Workflow, params
 
 	// Parse excluded modules
 	excludeList := parseExcludeList(params["exclude_modules"])
+	fuzzyExcludeList := parseExcludeList(params["fuzzy_exclude_modules"])
 
 	// Pre-load all modules in parallel for faster startup
 	execCtx.Logger.Debug("Pre-loading modules", zap.Int("count", len(flow.Modules)))
@@ -1812,8 +1869,8 @@ func (e *Executor) ExecuteFlow(ctx context.Context, flow *core.Workflow, params
 
 		modRef := moduleMap[modName]
 
-		// Check if module is excluded
-		if isModuleExcluded(modRef.Name, excludeList) {
+		// Check if module is excluded (exact match or fuzzy substring match)
+		if isModuleExcluded(modRef.Name, excludeList) || isFuzzyModuleExcluded(modRef.Name, fuzzyExcludeList) {
 			execCtx.Logger.Info("Skipping excluded module", zap.String("module", modRef.Name))
 			executed[modRef.Name] = true
 			// Unblock dependents even for excluded modules
@@ -2110,6 +2167,16 @@ func (e *Executor) executeStep(ctx context.Context, step *core.Step, execCtx *co
 		)
 		ok, err := e.functionRegistry.EvaluateCondition(renderedCondition, execCtx.GetVariables())
 		if err != nil {
+			// Check if skip() was called inside a pre_condition
+			if errors.Is(err, functions.ErrSkipModule) {
+				result.Status = core.StepStatusSkipped
+				result.Error = err
+				result.EndTime = time.Now()
+				if e.progressBar == nil {
+					e.printer.StepSkipped(step.Name)
+				}
+				return result, err
+			}
 			stepLogger.Debug("Pre-condition evaluation failed", zap.Error(err))
 			result.Status = core.StepStatusFailed
 			result.Error = fmt.Errorf("pre-condition evaluation failed: %w", err)
@@ -2243,6 +2310,18 @@ func (e *Executor) executeStep(ctx context.Context, step *core.Step, execCtx *co
 		sp.Stop()
 	}
 	if err != nil {
+		// Check if this is a skip-module signal (not a failure)
+		if errors.Is(err, functions.ErrSkipModule) {
+			result.Status = core.StepStatusSkipped
+			result.Error = err
+			result.EndTime = time.Now()
+			result.Duration = result.EndTime.Sub(result.StartTime)
+			if e.progressBar == nil {
+				e.printer.StepSkipped(step.Name)
+			}
+			return result, err
+		}
+
 		result.Status = core.StepStatusFailed
 		result.Error = err
 		result.EndTime = time.Now()

internal/executor/executor_test.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/j3ssie/osmedeus/v5/internal/config"
 	"github.com/j3ssie/osmedeus/v5/internal/core"
+	"github.com/j3ssie/osmedeus/v5/internal/parser"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -1677,3 +1678,143 @@ func TestExecutor_StepDependencies_FailedDep_SkipsDependent(t *testing.T) {
 		assert.NotEqual(t, core.StepStatusSuccess, stepBExists)
 	}
 }
+
+func TestExecutor_SkipModule(t *testing.T) {
+	ctx := context.Background()
+	cfg := testConfig(t)
+
+	module := &core.Workflow{
+		Name: "test-skip",
+		Kind: core.KindModule,
+		Steps: []core.Step{
+			{
+				Name:     "step-before",
+				Type:     core.StepTypeFunction,
+				Function: "log_info('before skip')",
+			},
+			{
+				Name:     "step-skip",
+				Type:     core.StepTypeFunction,
+				Function: "skip('target not applicable')",
+			},
+			{
+				Name:     "step-after",
+				Type:     core.StepTypeFunction,
+				Function: "log_info('after skip')",
+			},
+		},
+	}
+
+	executor := NewExecutor()
+	executor.SetDryRun(false)
+	executor.SetSpinner(false)
+
+	result, err := executor.ExecuteModule(ctx, module, map[string]string{
+		"target": "test",
+	}, cfg)
+
+	// skip() returns nil error (not a failure)
+	require.NoError(t, err)
+	assert.Equal(t, core.RunStatusSkipped, result.Status)
+	assert.Equal(t, "target not applicable", result.Message)
+
+	// step-before should have executed, step-after should NOT
+	assert.GreaterOrEqual(t, len(result.Steps), 2, "should have at least step-before and step-skip")
+
+	// Find step-after in results - it should not be present
+	for _, s := range result.Steps {
+		assert.NotEqual(t, "step-after", s.StepName, "step-after should not have executed")
+	}
+}
+
+func TestExecutor_SkipModulePreservesExports(t *testing.T) {
+	ctx := context.Background()
+	cfg := testConfig(t)
+
+	module := &core.Workflow{
+		Name: "test-skip-exports",
+		Kind: core.KindModule,
+		Steps: []core.Step{
+			{
+				Name:     "set-var",
+				Type:     core.StepTypeFunction,
+				Function: "set_var('my_key', 'my_value')",
+			},
+			{
+				Name:     "do-skip",
+				Type:     core.StepTypeFunction,
+				Function: "skip('done early')",
+			},
+		},
+	}
+
+	executor := NewExecutor()
+	executor.SetDryRun(false)
+	executor.SetSpinner(false)
+
+	result, err := executor.ExecuteModule(ctx, module, map[string]string{
+		"target": "test",
+	}, cfg)
+
+	require.NoError(t, err)
+	assert.Equal(t, core.RunStatusSkipped, result.Status)
+	assert.Equal(t, "done early", result.Message)
+}
+
+func TestIsFuzzyModuleExcluded(t *testing.T) {
+	tests := []struct {
+		name       string
+		moduleName string
+		fuzzyList  []string
+		expected   bool
+	}{
+		{"exact substring match", "recon-spider", []string{"spider"}, true},
+		{"prefix match", "spider-crawl", []string{"spider"}, true},
+		{"no match", "recon-dns", []string{"spider"}, false},
+		{"empty list", "recon-spider", nil, false},
+		{"empty pattern list", "recon-spider", []string{}, false},
+		{"multiple patterns first matches", "recon-spider", []string{"spider", "dns"}, true},
+		{"multiple patterns second matches", "recon-dns", []string{"spider", "dns"}, true},
+		{"multiple patterns none match", "recon-http", []string{"spider", "dns"}, false},
+		{"full name as pattern", "recon-spider", []string{"recon-spider"}, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := isFuzzyModuleExcluded(tt.moduleName, tt.fuzzyList)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestExecutor_FuzzyExcludeModules(t *testing.T) {
+	ctx := context.Background()
+	cfg := testConfig(t)
+
+	// Create a flow where all modules will be excluded by fuzzy match
+	flow := &core.Workflow{
+		Name: "test-fuzzy-exclude",
+		Kind: core.KindFlow,
+		Modules: []core.ModuleRef{
+			{Name: "recon-spider", Path: ""},
+			{Name: "spider-crawl", Path: ""},
+		},
+	}
+
+	loader := parser.NewLoader(cfg.WorkflowsPath)
+
+	exec := NewExecutor()
+	exec.SetDryRun(true)
+	exec.SetSpinner(false)
+	exec.SetLoader(loader)
+
+	// fuzzy_exclude_modules=spider should skip both recon-spider and spider-crawl
+	result, err := exec.ExecuteFlow(ctx, flow, map[string]string{
+		"target":                "test.example.com",
+		"fuzzy_exclude_modules": "spider",
+	}, cfg)
+
+	require.NoError(t, err)
+	assert.NotNil(t, result)
+	assert.Equal(t, core.RunStatusCompleted, result.Status)
+}

internal/executor/function_executor.go

@@ -2,6 +2,7 @@ package executor
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"sync"
 	"time"
@@ -68,6 +69,11 @@ func (e *FunctionExecutor) Execute(ctx context.Context, step *core.Step, execCtx
 	result.Duration = result.EndTime.Sub(result.StartTime)
 
 	if err != nil {
+		if errors.Is(err, functions.ErrSkipModule) {
+			result.Status = core.StepStatusSkipped
+			result.Error = err
+			return result, err
+		}
 		result.Status = core.StepStatusFailed
 		result.Error = err
 		return result, err

internal/functions/constants.go

@@ -1,5 +1,29 @@
 package functions
 
+import (
+	"errors"
+	"fmt"
+)
+
+// ErrSkipModule is a sentinel error used by skip() to signal that the
+// remaining steps in the current module should be skipped. The flow
+// continues to the next module.
+var ErrSkipModule = errors.New("skip module")
+
+// SkipModuleError carries an optional message and wraps ErrSkipModule
+// so that errors.Is(err, ErrSkipModule) works through the chain.
+type SkipModuleError struct {
+	Message string
+}
+
+func (e *SkipModuleError) Error() string {
+	return fmt.Sprintf("skip module: %s", e.Message)
+}
+
+func (e *SkipModuleError) Unwrap() error {
+	return ErrSkipModule
+}
+
 // Function name constants for easy reference and consistency
 // This file serves as a central reference for all available workflow functions
 
@@ -79,6 +103,7 @@ const (
 	FnPrintf         = "printf"       // printf(message) -> void (print message to stdout)
 	FnCatFile        = "cat_file"     // cat_file(path) -> void (print file content to stdout)
 	FnExit           = "exit"         // exit(code) -> void (exit scan with code)
+	FnSkip           = "skip"         // skip(message?) -> void (skip remaining steps in current module)
 	FnExecCmd        = "exec_cmd"     // exec_cmd(command) -> string (alias for bash)
 	FnBash           = "bash"
 	FnSleep          = "sleep"            // sleep(seconds) -> void (pause for n seconds)
@@ -391,6 +416,7 @@ func AllFunctions() []string {
 		FnPrintf,
 		FnCatFile,
 		FnExit,
+		FnSkip,
 		FnExecCmd,
 		FnBash,
 		FnSleep,
@@ -727,6 +753,7 @@ func FunctionRegistry() map[string][]FunctionInfo {
 			{FnPrintf, "printf(message)", "Print message to stdout", "void", "printf('Scan started')"},
 			{FnCatFile, "cat_file(path)", "Print file content to stdout", "void", "cat_file('{{Output}}/results.txt')"},
 			{FnExit, "exit(code)", "Exit scan with code", "void", "exit(1)"},
+			{FnSkip, "skip(message?)", "Skip remaining steps in current module and continue to next module", "void", "skip('target not applicable')"},
 			{FnBash, "bash(command)", "Execute bash command and return output", "string", "bash('whoami')"},
 			{FnExecCmd, "exec_cmd(command)", "Alias for bash(command)", "string", "exec_cmd('whoami')"},
 			{FnSleep, "sleep(seconds)", "Pause for n seconds", "void", "sleep(5)"},

internal/functions/goja_runtime.go

@@ -112,6 +112,7 @@ func (r *GojaRuntime) registerFunctionsOnVM(vm *goja.Runtime) {
 	_ = vm.Set(FnPrintf, vf.printf)
 	_ = vm.Set(FnCatFile, vf.catFile)
 	_ = vm.Set(FnExit, vf.exit)
+	_ = vm.Set(FnSkip, vf.skip)
 	_ = vm.Set(FnExecCmd, vf.execCmd)
 	_ = vm.Set(FnBash, vf.bash)
 	_ = vm.Set(FnSleep, vf.sleep)

internal/functions/util_functions.go

@@ -708,6 +708,18 @@ func (vf *vmFunc) exit(call goja.FunctionCall) goja.Value {
 	return goja.Undefined()
 }
 
+// skip stops execution of the remaining steps in the current module.
+// The flow continues to the next module. Accepts an optional message.
+// Usage: skip(message?) -> void
+func (vf *vmFunc) skip(call goja.FunctionCall) goja.Value {
+	msg := call.Argument(0).String()
+	if msg == "undefined" || msg == "" {
+		msg = "skip() called"
+	}
+	logger.Get().Info("Module skip requested: " + msg)
+	panic(vf.vm.NewGoError(&SkipModuleError{Message: msg}))
+}
+
 // execCmd executes a bash command and returns the stdout output
 // Usage: exec_cmd(command) -> string
 func (vf *vmFunc) execCmd(call goja.FunctionCall) goja.Value {