CLI skeleton for Detektor (.NET command-line interface)

[meisterware-admin]

Overview

Introduce the initial command-line interface (CLI) skeleton for the Detektor scanner.

This issue establishes the foundational CLI structure that will host all future scanning, reporting, and policy evaluation functionality.

The CLI will provide a consistent entry point for executing scans against repositories, agent configurations, workflows, and other artifacts.

This proposal focuses on creating the minimal CLI infrastructure required for Detektor v0.1, including command routing, argument parsing, and basic execution flow.

---

Motivation

Detektor is intended to function as a developer-friendly security scanner that integrates easily with CI pipelines and local developer workflows.

A CLI interface is essential because it enables:

• integration with CI systems such as GitHub Actions, GitLab CI, and Azure Pipelines
• execution in local developer environments
• deterministic invocation of scans from automation scripts
• consistent command-line behaviour across environments

Without a CLI entry point, Detektor cannot function as a practical scanning tool.

Establishing the CLI skeleton early allows other core components—such as artifact loading, rule execution, and report generation—to integrate into a stable execution pipeline.

---

Proposed Approach

Create a minimal Detektor CLI implemented in .NET using the System.CommandLine library.

The CLI will initially support a single command:

detektor scan <target>

Example usage:

detektor scan .

Initial responsibilities of the CLI skeleton include:

• defining the root CLI command
• implementing the scan command
• parsing CLI arguments and options
• invoking the scan pipeline (to be implemented in later issues)
• providing help and usage information

Proposed structure:

detektor
 └─ scan <target>

Where:

• <target> may represent a repository directory, agent configuration file, or workflow definition.

The CLI skeleton will not initially implement detection logic. Instead, it will provide the command execution entry point that later issues will connect to:

• artifact loading
• rule engine
• findings normalization
• OpenPAKT report generation

---

Alternatives Considered

1. Implement Detektor as a library first

An alternative approach would be to implement the scanner engine as a reusable library before creating a CLI.

However, since Detektor is intended primarily as a CLI security scanner, starting with the CLI entry point ensures early usability and integration testing.

2. Use an alternative CLI framework

Other CLI frameworks exist for .NET, but System.CommandLine provides a lightweight and well-supported option suitable for Detektor’s minimal MVP goals.

---

Risks and Trade-offs

Potential downsides include:

Early CLI design constraints

If the CLI structure is poorly designed, later commands or options may require refactoring.

Premature command structure decisions

Some command patterns may evolve as the scanner capabilities grow.

However, this risk is mitigated by keeping the initial CLI structure minimal.

---

Open Questions

• Should Detektor support multiple scan modes in v0.1 (for example scan, validate, report) or only a single scan command?
• Should CLI output support multiple formats (for example json, sarif) in v0.1 or only OpenPAKT JSON?
• Should the CLI support configuration files (for example detektor.yaml) in the initial release?

---

Examples

Example CLI usage:

detektor scan .

Future CLI usage may support options such as:

detektor scan ./repo --output report.json

or

detektor scan ./repo --policy policy.yaml

---

Next Steps

If this proposal is accepted:

1. Create the Detektor CLI project using .NET.

2. Implement the root CLI command and scan command.

3. Add argument parsing for scan targets.

4. Implement CLI help and usage output.

5. Prepare the CLI execution pipeline so future issues can integrate:

   • artifact loading
   • rule engine
   • findings generation
   • OpenPAKT report writing.