Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 12 additions & 22 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Secure Engine follows untrusted values across files and helpers, then reports re

## What it detects

Version 0.1.10 ships ten deterministic rule families:
The current development tree defines thirteen deterministic rule families:

- `SE1001`: untrusted input reaching command execution;
- `SE1002`: untrusted input reaching dynamically constructed or raw SQL;
Expand All @@ -24,7 +24,10 @@ Version 0.1.10 ships ten deterministic rule families:
- `SE1007`: exposed handlers reaching sensitive operations without a dominating authorization guard;
- `SE1008`: untrusted input reaching CLI option parsing without an end-of-options boundary;
- `SE1009`: untrusted input reaching a shared prototype mutation;
- `SE1010`: sensitive configuration reaching logging or an AI/LLM provider payload.
- `SE1010`: classified sensitive data reaching local diagnostic output or a remote provider boundary;
- `SE1011`: a proven Node `net.Server` receiver calling `listen(port)` without an explicit host, emitted as a qualified network-exposure lead rather than a vulnerability verdict.
- `SE1012`: workspace, workspace-folder, or environment configuration reaching an exact process binary, shell program, argv, environment, cwd, or shell-mode boundary without a fresh same-scope trust proof.
- `SE1013`: structurally incomplete manifest-authority or lifecycle-policy composition, emitted only as an explicit abstention pending runtime reachability, actor, boundary, and impact proof.

The analyzer supports bounded inter-file propagation, value-preserving helpers, static-property identity, shell program-text classification, exact path and URL policy projection, and principal/resource-aware authorization evidence. Ambiguous flows fail conservatively instead of inventing proof.

Expand All @@ -48,6 +51,7 @@ Scan a repository with the installed CLI:
```bash
secure scan .
secure scan . --format secure-json-v1 --output report.json
secure scan . --full-graph --output report-with-global-graph.json
secure scan . --format sarif --output report.sarif
secure scan . --include 'src/**' --exclude 'src/generated/**' --max-files 50000
secure rules list
Expand All @@ -69,6 +73,8 @@ cargo run -p secure-desktop -- .

Additional workflows include baselines, history, suppressions, cache control, schema export, diagnostics, cancellation, and bounded scans. Run `secure --help` or `secure <command> --help` for the complete interface.

Normal `secure-json-v1` CLI reports retain only finding and explicit-abstention evidence neighborhoods while exposing complete analyzed graph and fact counts separately. The lanes are structurally disjoint: an explicit abstention is never serialized as a finding. Serialization streams to an atomic temporary file and fails closed above the default 64 MiB output budget; change the explicit budget with `--max-output-bytes`. Use `--full-graph` only when complete facts and the global graph are required. Both projections are deterministic and declare their scope and budget in the report.

## Independent evaluation

Secure Engine 0.1.8 was evaluated once against a newly frozen Secure Bench v4 holdout containing 28 vulnerable cases and 28 paired controls. The campaign completed all attempts without retries or operational failures. A post-open certification corrected a location-matching defect in the benchmark scorer by recomputing metrics from the immutable raw evidence without replaying scanners.
Expand Down Expand Up @@ -96,7 +102,7 @@ These limits can produce false negatives. Parser recovery and framework conventi

## Structured evidence and privacy

The stable public projection includes taxonomy 1.0.0, Evidence Contract v2, `secure-json-v1`, SARIF 2.1.0, deterministic fingerprints, and private parse cache v20. Older cache envelopes produce safe misses.
The stable public projection includes taxonomy 1.0.0, Evidence Contract v2, `secure-json-v1`, SARIF 2.1.0, deterministic fingerprints, and private parse cache v23. Older cache envelopes produce safe misses.

AI validation never originates, deletes, or rewrites a finding. It requires project configuration, an exact redacted payload preview, and per-operation consent. Provider credentials are read only from the configured environment variable and are never serialized. See [AI validation](./docs/ai-validation.md) and [Evidence Contract v2](./docs/evidence-contract-v2.md).

Expand Down
56 changes: 43 additions & 13 deletions apps/secure-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,16 @@ use secure_engine::{
ScanError, ScanReport, ScanRequest, Suppression, compare_baseline, configured_provider,
create_baseline, default_ai_cache_directory, default_history_directory, explain_finding,
preview_finding, provider_descriptors, read_ai_configuration, rules, scan_repository,
serialize_export, validate_baseline, validate_finding_with_ai, validation_document,
write_export, write_json_artifact,
scan_repository_compact, serialize_export_bounded, set_report_output_budget, validate_baseline,
validate_finding_with_ai, validation_document, write_export_bounded, write_json_artifact,
};

const EXIT_POLICY_FINDINGS: u8 = 1;
const EXIT_INVALID_INPUT: u8 = 2;
const EXIT_UNSUPPORTED_SCHEMA: u8 = 3;
const EXIT_CANCELLED: u8 = 4;
const EXIT_INTERNAL_FAILURE: u8 = 5;
const DEFAULT_REPORT_OUTPUT_BYTES: u64 = 64 * 1024 * 1024;

#[derive(Debug, Parser)]
#[command(
Expand Down Expand Up @@ -231,6 +232,12 @@ struct ScanArgs {
/// Maximum findings retained after deduplication.
#[arg(long, default_value_t = 10_000)]
max_findings: usize,
/// Retain the complete facts and global evidence graph instead of the compact projection.
#[arg(long)]
full_graph: bool,
/// Maximum serialized report bytes; exceeding it fails closed without partial output.
#[arg(long, default_value_t = DEFAULT_REPORT_OUTPUT_BYTES)]
max_output_bytes: u64,
/// Exact suppression: `RULE_ID:RELATIVE_PATH:START_BYTE:REASON`. Repeatable.
#[arg(long = "suppress", value_name = "RULE:PATH:BYTE:REASON")]
suppressions: Vec<String>,
Expand Down Expand Up @@ -387,6 +394,12 @@ fn run_scan(arguments: ScanArgs) -> Result<u8, (u8, String)> {
"resource limits must be greater than zero".into(),
));
}
if arguments.max_output_bytes == 0 {
return Err((
EXIT_INVALID_INPUT,
"max_output_bytes must be greater than zero".into(),
));
}

let cancellation = CancellationToken::new();
install_cancellation(&cancellation)?;
Expand Down Expand Up @@ -425,27 +438,41 @@ fn run_scan(arguments: ScanArgs) -> Result<u8, (u8, String)> {
let quiet = arguments.quiet;
let verbose = arguments.verbose;
let repository_path = request.repository.clone();
let report = scan_repository(&request, &cancellation, |event| {
print_progress(&event, quiet, verbose);
})
let mut report = if arguments.full_graph {
scan_repository(&request, &cancellation, |event| {
print_progress(&event, quiet, verbose);
})
} else {
scan_repository_compact(
&request,
&cancellation,
|event| print_progress(&event, quiet, verbose),
arguments.max_output_bytes,
)
}
.map_err(scan_error)?;
if cancellation.is_cancelled() {
return Err((EXIT_CANCELLED, "scan cancelled".into()));
}
if arguments.full_graph {
set_report_output_budget(&mut report, arguments.max_output_bytes).map_err(scan_error)?;
}

if let Some(output) = arguments.output {
write_export(&report, export_format, &output, &cancellation)
.map_err(|error| export_error(&error, "report"))?;
write_export_bounded(
&report,
export_format,
&output,
&cancellation,
arguments.max_output_bytes,
)
.map_err(|error| export_error(&error, "report"))?;
if !quiet {
eprintln!("secure: wrote complete report to {}", output.display());
}
} else {
let bytes = serialize_export(&report, export_format).map_err(|_| {
(
EXIT_INTERNAL_FAILURE,
"complete report could not be serialized".into(),
)
})?;
let bytes = serialize_export_bounded(&report, export_format, arguments.max_output_bytes)
.map_err(|error| export_error(&error, "report"))?;
write_stdout(&bytes).map_err(|message| (EXIT_INTERNAL_FAILURE, message))?;
}
if arguments.save_history {
Expand Down Expand Up @@ -1017,6 +1044,9 @@ fn export_error(error: &secure_engine::ExportError, artifact: &str) -> (u8, Stri
EXIT_INVALID_INPUT,
format!("{artifact} could not be written atomically"),
),
secure_engine::ExportError::OutputBudgetExceeded { .. } => {
(EXIT_INVALID_INPUT, format!("{}: {error}", error.code()))
}
}
}

Expand Down
40 changes: 38 additions & 2 deletions apps/secure-cli/tests/cli_contract.rs
Original file line number Diff line number Diff line change
Expand Up @@ -222,20 +222,50 @@ fn malformed_phase_one_controls_use_invalid_input_exit_code()
"--max-graph-edges",
"--max-interprocedural-depth",
"--max-findings",
"--full-graph",
"--max-output-bytes",
"--suppress",
] {
assert!(help_text.contains(flag), "missing {flag}");
}
Ok(())
}

#[test]
fn report_output_budget_fails_closed_without_a_partial_document()
-> Result<(), Box<dyn std::error::Error>> {
let temporary = tempdir()?;
let report = temporary.path().join("too-small.json");
let fixture = concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../fixtures/integration-project"
);
let output = secure()
.args([
"scan",
fixture,
"--no-cache",
"--full-graph",
"--max-output-bytes",
"128",
"--output",
])
.arg(&report)
.output()?;
assert_eq!(output.status.code(), Some(2));
assert!(output.stdout.is_empty());
assert!(!report.exists());
assert!(String::from_utf8(output.stderr)?.contains("output-budget-exceeded"));
Ok(())
}

#[test]
fn phase_three_rule_catalog_is_stable_machine_output() -> Result<(), Box<dyn std::error::Error>> {
let output = secure().args(["rules", "list"]).output()?;
assert!(output.status.success());
assert!(output.stderr.is_empty());
let catalog: Vec<secure_engine::RuleMetadata> = serde_json::from_slice(&output.stdout)?;
assert_eq!(catalog.len(), 10);
assert_eq!(catalog.len(), 13);
assert!(catalog.iter().take(7).all(|rule| {
rule.taxonomy.is_some() && rule.primary_cwe.is_some() && rule.taxonomy_provenance.is_some()
}));
Expand All @@ -248,7 +278,7 @@ fn phase_three_rule_catalog_is_stable_machine_output() -> Result<(), Box<dyn std
);
assert_eq!(
catalog.last().map(|rule| rule.rule_id.as_str()),
Some("SE1010")
Some("SE1013")
);
Ok(())
}
Expand All @@ -266,6 +296,12 @@ fn policy_exit_and_finding_explanation_use_the_shared_report()
assert_eq!(scan.status.code(), Some(1));
assert!(scan.stdout.is_empty());
let report: serde_json::Value = serde_json::from_slice(&fs::read(&report_path)?)?;
assert_eq!(report["graph"]["scope"], "finding-evidence");
let retained_nodes = report["graph"]["nodes"].as_array().map_or(0, Vec::len);
assert!(
report["graph"]["total_nodes"].as_u64().unwrap_or_default()
>= u64::try_from(retained_nodes).unwrap_or(u64::MAX)
);
let finding_id = report["findings"]
.as_array()
.and_then(|findings| {
Expand Down
2 changes: 1 addition & 1 deletion crates/secure-engine/src/cache.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ use crate::parser::{
use crate::workspace::{ReadOutcome, read_file_no_follow};
use crate::{CacheControl, CancellationToken, ScanConfiguration, ScanError};

const CACHE_FORMAT: &str = "secure-parse-cache-v20";
const CACHE_FORMAT: &str = "secure-parse-cache-v23";
const MAX_CACHE_ENTRY_BYTES: u64 = 16 * 1024 * 1024;
const MAX_CACHE_DIRECTORY_ENTRIES: usize = 100_000;
static TEMPORARY_COUNTER: AtomicU64 = AtomicU64::new(0);
Expand Down
10 changes: 8 additions & 2 deletions crates/secure-engine/src/evidence_contract.rs
Original file line number Diff line number Diff line change
Expand Up @@ -238,11 +238,12 @@ pub(crate) fn finding_contract_v2(
fn contract_step(rule_id: &str, step: &EvidencePathStep) -> Option<EvidenceContractPathStepV2> {
let semantic = step.semantic.as_ref()?;
let (role, effect, summarizable) = match semantic.role {
EvidenceSemanticRole::UntrustedSource => (
EvidenceSemanticRole::UntrustedSource | EvidenceSemanticRole::SensitiveSource => (
EvidenceContractRoleV2::Source,
EvidenceEffectV2::PreservesInfluence,
false,
),
EvidenceSemanticRole::ConfigurationSource | EvidenceSemanticRole::Receiver => return None,
EvidenceSemanticRole::Transformation => (
EvidenceContractRoleV2::Propagation,
if semantic.certainty == "proven" {
Expand Down Expand Up @@ -305,7 +306,12 @@ fn sink_kind(identity: &str) -> EvidenceSinkKindV2 {
match identity {
"sink.process-execution" => EvidenceSinkKindV2::OsCommandExecution,
"sink.database-query" => EvidenceSinkKindV2::SqlQueryExecution,
"sink.filesystem-operation" => EvidenceSinkKindV2::FilesystemRead,
"sink.filesystem-operation"
| "sink.filesystem-read"
| "sink.filesystem-write"
| "sink.filesystem-remove"
| "sink.filesystem-rename"
| "sink.filesystem-metadata-change" => EvidenceSinkKindV2::FilesystemRead,
"sink.outbound-request" => EvidenceSinkKindV2::OutboundRequest,
"sink.redirect" => EvidenceSinkKindV2::RedirectResponse,
"sink.dynamic-code-execution" => EvidenceSinkKindV2::DynamicCodeEvaluation,
Expand Down
Loading