Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

feat(imports): import Tenable One code repository findings locally (#2343)

Michael D'Angelo6565fd2b1e6c
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.md
index 08ed89ab1..50133e2fd 100644
--- a/docs/scanner-imports/README.md
+++ b/docs/scanner-imports/README.md
@@ -50,6 +50,7 @@ unless an input is marked local only. Cloud must support the selected provider.
| [Semgrep](semgrep.md) | CLI/CI JSON, SARIF, Platform Web API reports, or selected Guardian findings (local only) |
| [Snyk](snyk.md) | CLI JSON, plugin exports, SARIF, or monitored Code and Open Source issues |
| [SonarQube Cloud](sonar.md) | Issues selected with the signed-in Sonar CLI, or saved issue-search pages |
+| [Tenable One](tenable.md) | Selected Code Repository inventory findings (experimental, local only) |
| [Trivy](trivy.md) | Native schema-v2 repository or filesystem JSON, optionally gzip-compressed |
| [Veracode Static Analysis](veracode.md) | Findings API pages for one application's policy flaws |
| [Wiz](wiz.md) | Native JSON, normalized JSONL, or detailed repository package vulnerability CSV |
diff --git a/docs/scanner-imports/schema-guide.md b/docs/scanner-imports/schema-guide.md
index d9addae57..9f8e203dd 100644
--- a/docs/scanner-imports/schema-guide.md
+++ b/docs/scanner-imports/schema-guide.md
@@ -26,6 +26,7 @@ which changes can give an occurrence a different ID.
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Amazon Inspector](inspector.md), [Endor Labs](endor.md), [SonarQube Cloud](sonar.md) | Inspector finding ARN, Endor Finding UUID or Sonar issue key. Endor native JSON and SARIF use the same UUID. |
| [AWS Continuum](continuum.md) | Continuum finding ARN. A list summary and a detailed response for that ARN identify the same finding. |
+| [Tenable One local pilot](tenable.md) | Exact Tenable `finding_id` within the local checkout and a stable tenant/asset source key. Use the Code Repository asset UUID in the key. |
| [Checkmarx SAST](checkmarx.md) | Checkmarx One uses the similarity ID and result hash. CxSAST scopes the similarity ID and ordered flow to the project and query. |
| [Wiz](wiz.md) | Package occurrence ID, or a SAST, repository-secret or IaC occurrence ID prefixed with its family. Normalized JSONL uses the supplied ID. |
| [GitHub Dependabot](github-dependabot.md), [code scanning](github-code-scanning.md) | Host, repository, alert family and alert number. Code scanning also includes the selected ref. Two alerts citing one GHSA remain separate. |
diff --git a/docs/scanner-imports/tenable.md b/docs/scanner-imports/tenable.md
new file mode 100644
index 000000000..1805f66d8
--- /dev/null
+++ b/docs/scanner-imports/tenable.md
@@ -0,0 +1,47 @@
+# Import Tenable One code repository findings locally
+
+Select a **Code Repository** in Tenable Exposure Management Inventory. Copy its asset UUID and the finding UUIDs you want. Verify the HTTPS clone URL independently in your source control system and use a checkout with a matching Git fetch remote. [Tenable asset details](https://docs.tenable.com/exposure-management/Content/inventory/asset-details.htm)
+
+## Export the selection
+
+Run the examples from the Codex Security source tree. Set `TENABLE_ACCESS_KEY` and `TENABLE_SECRET_KEY` for a tenant with inventory export access on `cloud.tenable.com`. Use a private report directory outside both checkouts.
+
+```sh
+umask 077
+reports=/private/path/tenable-export
+mkdir -p "$reports"
+asset_id=SELECTED_ASSET_UUID
+repository_url=https://github.com/example/project
+checkout=/path/to/project
+python3 examples/tenable-one/download.py --asset-id "$asset_id" \
+ --finding-id SELECTED_FINDING_UUID --repository-url "$repository_url" \
+ --output "$reports/selection.json"
+```
+
+Repeat `--finding-id` for additional findings. The helper requests separate asset and finding exports, polls for completion, downloads the CSV chunks, and checks each finding against the selected asset. [Export assets](https://developer.tenable.com/reference/inventory-export-assets) · [Export findings](https://developer.tenable.com/reference/inventory-export-findings) · [Export status](https://developer.tenable.com/reference/inventory-export-status) · [Download chunks](https://developer.tenable.com/reference/inventory-export-download)
+
+### From existing CSV exports
+
+Use uncompressed CSVs with machine headers (`use_readable_name=false`). The asset export needs `asset_id,asset_class,asset_name`. The findings export needs `asset_id,finding_id,finding_name,finding_severity,state` for the selected repository. The default title header `finding_detection_name` is also accepted. Include `finding_description` and `finding_solution` when available. [Asset properties](https://developer.tenable.com/reference/inventory-asset-properties-list) · [Finding properties](https://developer.tenable.com/reference/inventory-finding-properties-list)
+
+```sh
+python3 examples/tenable-one/capture.py --assets "$reports/assets.csv" \
+ --findings "$reports/findings.csv" --asset-id "$asset_id" \
+ --repository-url "$repository_url" --output "$reports/selection.json"
+```
+
+Pass additional finding chunks after `--findings`. To retain file locations, add `--path-column file_path --line-column code_line_number`, substituting your tenant's column names. A path is repository-relative. A zero line number leaves the line unspecified.
+
+## Preview, save and read back
+
+Use the CLI built from this checkout. Choose a stable tenant alias so the same finding can be matched on later imports. [Source build setup](../../sdk/typescript/TESTING.md)
+
+```sh
+export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
+cli="$PWD/sdk/typescript/bin/codex-security.mjs"
+node "$cli" publish findings "$reports/selection.json" --provider tenable \
+ --to local --repository "$checkout" --source-repository-url "$repository_url" \
+ --source-key "TENANT_ALIAS/$asset_id" --dry-run --format json
+```
+
+Check the preview against your selection. Remove `--dry-run` and confirm to save, then run `node "$cli" findings imported "$checkout" --format json`. The saved record retains Tenable's exact finding ID and state. Its Codex assessment starts as `not_assessed`. With the same source key, changed evidence updates that record and identical evidence preserves its version.
diff --git a/examples/README.md b/examples/README.md
index 270f94e8c..0181a4cfc 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -6,6 +6,7 @@
| Supply your own validation test | [Custom validation demo](custom-validation/README.md). Run the local HTTP test on its own or let a model-backed scan invoke it. |
| Scan pull requests and repositories with GitHub Actions | [GitHub Actions with Amazon Bedrock](github-actions/README.md) uses AWS OIDC and saves SARIF and readable reports. |
| Scan Azure Repos from a central pipeline | [Azure Pipelines with Amazon Bedrock](azure-pipelines/README.md) runs manual full or committed-diff scans. |
+| Import Tenable One findings locally | [Tenable One export guide](../docs/scanner-imports/tenable.md) shows how to select code repository findings. |
| Prepare a ServiceNow AVIT export | [AVIT template](servicenow-avit-template.csv). Replace the synthetic application and assignment values before using it as input to [export findings for ServiceNow](../sdk/typescript/docs/cli.md#export-findings-for-servicenow). |
| Prepare findings for Cloud | [Findings CSV template](findings.csv). Add one row per finding and preview the file as shown below. |
diff --git a/examples/tenable-one/capture.py b/examples/tenable-one/capture.py
new file mode 100644
index 000000000..9eedf4cb6
--- /dev/null
+++ b/examples/tenable-one/capture.py
@@ -0,0 +1,173 @@
+"""Capture one Code Repository asset and its findings from Tenable One CSV exports."""
+
+import argparse
+import csv
+import json
+import sys
+from io import TextIOWrapper
+from pathlib import Path
+from uuid import UUID
+
+PLUGIN_SCRIPTS = Path(__file__).resolve().parents[2] / "plugins/codex-security/scripts"
+sys.path.insert(0, str(PLUGIN_SCRIPTS))
+from finalize_scan_contract import _validate_remote, write_scan_local_bytes
+
+ASSET_FIELDS = ("asset_id", "asset_class", "asset_name")
+FINDING_FIELDS = ("asset_id", "finding_id", "finding_name", "severity", "state")
+FINDING_ALIASES = {
+ "finding_detection_name": "finding_name",
+ "finding_severity": "severity",
+ "finding_solution": "solution",
+ "finding_description": "description",
+}
+
+
+def file_chunks(paths):
+ for path in paths:
+ yield path, path.open("rb")
+
+
+def csv_rows(chunks, required, aliases=None, source_columns=()):
+ """Read each chunk's header separately, including header-only chunks."""
+ # A single exported description can exceed Python's default 128 KiB field limit.
+ # Tenable permits CSV chunks up to 100 MiB.
+ csv.field_size_limit(max(csv.field_size_limit(), 100 * 1024 * 1024))
+ first_header = None
+ for path, chunk in chunks:
+ with TextIOWrapper(chunk, encoding="utf-8-sig", newline="") as stream:
+ reader = csv.DictReader(stream, strict=True)
+ header = reader.fieldnames or []
+ # An export's default names can differ from explicitly selected properties.
+ mapped = {
+ source: target
+ for source, target in (aliases or {}).items()
+ if source in header and target not in header
+ }
+ missing = set(required).difference(header, mapped.values())
+ missing.update(set(source_columns).difference(header))
+ if missing:
+ raise ValueError(f"{path}: missing CSV columns: {', '.join(sorted(missing))}")
+ if len(set(header)) != len(header) or "" in header:
+ raise ValueError(f"{path}: duplicate or empty CSV column name")
+ if first_header is not None and header != first_header:
+ raise ValueError(f"{path}: column names or order differ between chunks")
+ first_header = header
+ for row in reader:
+ context = f"{path}, line {reader.line_num}"
+ if None in row or None in row.values():
+ raise ValueError(f"{context}: row width does not match its CSV header")
+ row.update({target: row[source] for source, target in mapped.items()})
+ yield context, row
+
+
+def required_values(fields, row, context):
+ for field in fields:
+ if not row[field].strip():
+ raise ValueError(f"{context}: missing {field}")
+ return {field: row[field] for field in fields}
+
+
+def validate_repository_url(repository_url):
+ _validate_remote(repository_url, "--repository-url")
+ if not repository_url.lower().startswith("https://"):
+ raise ValueError("--repository-url must be the repository's HTTPS URL")
+
+
+def read_asset(chunks, asset_id, *, exact=False):
+ asset = None
+ for context, row in csv_rows(chunks, ASSET_FIELDS):
+ if row["asset_id"].lower() != asset_id:
+ if exact:
+ raise ValueError(f"{context}: API returned an unrequested asset")
+ continue
+ if asset is not None:
+ raise ValueError(f"{context}: multiple inventory rows match the selected asset ID")
+ asset = required_values(ASSET_FIELDS, row, context)
+ if asset["asset_class"] != "CODE_REPOSITORY":
+ raise ValueError(f"{context}: selected asset must have asset_class CODE_REPOSITORY")
+ if asset is None:
+ raise ValueError("Selected asset ID was not found in the available asset chunks")
+ return asset
+
+
+def read_findings(chunks, asset_id, path_column, line_column):
+ source_columns = [key for key in (path_column, line_column) if key]
+ findings = {}
+ for context, row in csv_rows(chunks, FINDING_FIELDS, FINDING_ALIASES, source_columns):
+ if row["asset_id"].lower() != asset_id:
+ raise ValueError(f"{context}: finding belongs to a different or missing asset_id")
+ finding = required_values(FINDING_FIELDS, row, context)
+ if finding["finding_id"] in findings:
+ raise ValueError(f"{context}: duplicate finding_id in the selected export")
+ for field in ("description", "solution"):
+ if row.get(field):
+ finding[field] = row[field]
+ if path_column and row[path_column].strip():
+ finding["code_file_path"] = row[path_column]
+ if line_column and row[line_column].strip():
+ line = row[line_column].strip()
+ if not line.isascii() or not line.isdecimal():
+ raise ValueError(f"{context}: {line_column} must be a nonnegative integer")
+ number = int(line)
+ if number > 0:
+ if "code_file_path" not in finding:
+ raise ValueError(
+ f"{context}: a code line number requires a mapped repository path"
+ )
+ finding["code_line_number"] = number
+ findings[finding["finding_id"]] = finding
+ return list(findings.values())
+
+
+def write_selection(output, asset, repository_url, findings):
+ selection = {
+ "format": "tenable-one-code-repository/v1",
+ "asset": asset,
+ "repository_url": repository_url,
+ "findings": findings,
+ }
+ payload = (json.dumps(selection, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+ write_scan_local_bytes(
+ output.parent,
+ output.name,
+ payload,
+ external_name=True,
+ owner_read_write=True,
+ replace_existing=False,
+ )
+
+
+def selection_parser(description):
+ parser = argparse.ArgumentParser(description=description)
+ parser.add_argument("--asset-id", required=True, help="Tenable Code Repository asset UUID")
+ parser.add_argument("--repository-url", required=True, help="Canonical HTTPS repository URL")
+ parser.add_argument("--output", required=True, type=Path, help="New local selection JSON file")
+ return parser
+
+
+def main():
+ parser = selection_parser(__doc__)
+ parser.add_argument("--assets", required=True, type=Path, help="Asset inventory CSV")
+ parser.add_argument(
+ "--findings", required=True, type=Path, nargs="+", help="Findings CSV chunks"
+ )
+ parser.add_argument("--path-column", help="Verified export column for the repository file path")
+ parser.add_argument(
+ "--line-column", help="Verified export column for the one-based line number"
+ )
+ args = parser.parse_args()
+ try:
+ asset_id = str(UUID(args.asset_id))
+ validate_repository_url(args.repository_url)
+ asset = read_asset(file_chunks([args.assets]), asset_id)
+ findings = read_findings(
+ file_chunks(args.findings), asset_id, args.path_column, args.line_column
+ )
+ write_selection(args.output, asset, args.repository_url, findings)
+ except (ValueError, OSError, csv.Error) as exc:
+ parser.exit(1, f"{parser.prog}: {exc}\n")
+ print(f"Wrote {len(findings)} finding(s) to {args.output}.")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/tenable-one/download.py b/examples/tenable-one/download.py
new file mode 100644
index 000000000..2c911daba
--- /dev/null
+++ b/examples/tenable-one/download.py
@@ -0,0 +1,164 @@
+"""Download selected Tenable One Code Repository findings to a local selection file."""
+
+import csv
+import http.client
+import json
+import os
+import time
+from io import BytesIO
+from urllib.parse import urlencode
+from uuid import UUID
+
+from capture import (
+ ASSET_FIELDS,
+ read_asset,
+ read_findings,
+ selection_parser,
+ validate_repository_url,
+ write_selection,
+)
+
+EXPORT_PATH = "/api/v1/t1/inventory/export"
+FINDING_PROPERTIES = (
+ "asset_id",
+ "finding_id",
+ "finding_name",
+ "finding_severity",
+ "state",
+ "finding_description",
+ "finding_solution",
+ "file_path",
+ "code_line_number",
+)
+# The Inventory Export API uses 20 MiB CSV chunks by default.
+MAX_CHUNK_BYTES = 20 * 1024 * 1024
+
+
+def tenable_request(access_key, secret_key):
+ # http.client includes malformed header values in its exception messages.
+ if any(not key.isascii() or not key.isprintable() for key in (access_key, secret_key)):
+ raise ValueError("Tenable API keys must be printable ASCII header values")
+
+ def request(method, path, payload=None):
+ # A fixed-origin HTTPSConnection does not follow redirects or forward credentials.
+ headers = {"X-ApiKeys": f"accessKey={access_key};secretKey={secret_key}"}
+ body = None
+ if payload is not None:
+ headers["Content-Type"] = "application/json"
+ body = json.dumps(payload)
+ # A chunk GET may return 204 while its contents are being prepared.
+ retries_left = 4 if method == "GET" and "/download/" in path else 0
+ while True:
+ connection = http.client.HTTPSConnection("cloud.tenable.com", timeout=30)
+ try:
+ connection.request(method, path, body=body, headers=headers)
+ response = connection.getresponse()
+ if response.status == 200:
+ data = response.read(MAX_CHUNK_BYTES + 1)
+ if len(data) > MAX_CHUNK_BYTES:
+ raise ValueError("Tenable response exceeds the requested chunk size")
+ return data
+ if response.status != 204 or retries_left == 0:
+ break
+ finally:
+ connection.close()
+ retries_left -= 1
+ time.sleep(2)
+ raise ValueError(f"Tenable returned HTTP {response.status} for {method} {path}")
+
+ return request
+
+
+def export_chunks(kind, property_name, selected_id, columns, request, sleep):
+ query = urlencode(
+ {
+ "properties": ",".join(columns),
+ "file_format": "CSV",
+ "use_readable_name": "false",
+ "max_chunk_file_size": MAX_CHUNK_BYTES,
+ }
+ )
+ payload = {"filters": [{"property": property_name, "operator": "=", "value": [selected_id]}]}
+ job = json.loads(request("POST", f"{EXPORT_PATH}/{kind}?{query}", payload))
+ export_id = job.get("export_id") if isinstance(job, dict) else None
+ if not export_id or not isinstance(export_id, str):
+ raise ValueError("Tenable did not return an export ID")
+ job_id = str(UUID(export_id))
+ job_path = f"{EXPORT_PATH}/{job_id}"
+ for _ in range(60):
+ status = json.loads(request("GET", f"{job_path}/status"))
+ if not isinstance(status, dict) or status.get("export_id") != export_id:
+ raise ValueError("Tenable returned a status for an unexpected export ID")
+ if status.get("status") == "FINISHED":
+ break
+ if status.get("status") not in ("QUEUED", "PROCESSING"):
+ raise ValueError(f"Tenable export {job_id} ended with status {status.get('status')}")
+ sleep(2)
+ else:
+ raise ValueError(f"Tenable export {job_id} did not finish within 60 polls")
+
+ chunks = status.get("chunks_available")
+ if not isinstance(chunks, list) or any(type(chunk) is not int or chunk < 0 for chunk in chunks):
+ raise ValueError("Tenable returned invalid chunk numbers")
+ if len(set(chunks)) != len(chunks):
+ raise ValueError("Tenable returned duplicate chunk numbers")
+ for chunk in chunks:
+ path = f"{job_path}/download/{chunk}"
+ yield path, BytesIO(request("GET", path))
+
+
+def download(asset_id, finding_ids, repository_url, output, request, sleep=time.sleep):
+ asset_id = str(UUID(asset_id))
+ finding_ids = [str(UUID(value)) for value in finding_ids]
+ if not finding_ids or len(set(finding_ids)) != len(finding_ids):
+ raise ValueError("Select one or more distinct Tenable finding UUIDs")
+ validate_repository_url(repository_url)
+ if output.exists():
+ raise FileExistsError(f"Selection file already exists: {output}")
+
+ assets = export_chunks("assets", "asset_id", asset_id, ASSET_FIELDS, request, sleep)
+ asset = read_asset(assets, asset_id, exact=True)
+ findings = []
+ for finding_id in finding_ids:
+ # finding_id is a single-value filter. On finding exports, asset_id is read-only.
+ chunks = export_chunks(
+ "findings", "finding_id", finding_id, FINDING_PROPERTIES, request, sleep
+ )
+ rows = read_findings(chunks, asset_id, "file_path", "code_line_number")
+ if len(rows) != 1 or rows[0]["finding_id"].lower() != finding_id:
+ raise ValueError(f"Tenable did not return exactly the selected finding {finding_id}")
+ findings.extend(rows)
+ write_selection(output, asset, repository_url, findings)
+ return len(findings)
+
+
+def main():
+ parser = selection_parser(__doc__)
+ parser.add_argument(
+ "--finding-id",
+ action="append",
+ required=True,
+ help="Finding UUID; repeat for each selection",
+ )
+ args = parser.parse_args()
+ try:
+ access_key = os.environ.get("TENABLE_ACCESS_KEY")
+ secret_key = os.environ.get("TENABLE_SECRET_KEY")
+ if not access_key or not secret_key:
+ raise ValueError(
+ "Set TENABLE_ACCESS_KEY and TENABLE_SECRET_KEY for your Tenable tenant"
+ )
+ count = download(
+ args.asset_id,
+ args.finding_id,
+ args.repository_url,
+ args.output,
+ tenable_request(access_key, secret_key),
+ )
+ except (ValueError, OSError, csv.Error, http.client.HTTPException) as exc:
+ parser.exit(1, f"{parser.prog}: {exc}\n")
+ print(f"Wrote {count} finding(s) to {args.output}.")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/tenable-one/test_capture.py b/examples/tenable-one/test_capture.py
new file mode 100644
index 000000000..28e075a65
--- /dev/null
+++ b/examples/tenable-one/test_capture.py
@@ -0,0 +1,161 @@
+import csv
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+CAPTURE = Path(__file__).with_name("capture.py")
+ASSET_ID = "6e51b7ca-7ca3-48d0-990f-65a86af6b9c8"
+OTHER_ID = "3b1febad-1a8a-414a-8302-20cff925f4af"
+URL = "https://example.org/example/repo"
+ASSET = {"asset_id": ASSET_ID, "asset_name": "example/repo", "asset_class": "CODE_REPOSITORY"}
+DEVICE = {**ASSET, "asset_id": OTHER_ID, "asset_class": "DEVICE"}
+FINDING = {
+ "asset_id": ASSET_ID,
+ "finding_id": "Demo:0001",
+ "finding_name": "Example finding",
+ "severity": "HIGH",
+ "state": "ACTIVE",
+}
+LOCATIONS = ["--path-column", "src", "--line-column", "pos"]
+
+
+class CaptureTests(unittest.TestCase):
+ def setUp(self):
+ temp = tempfile.TemporaryDirectory()
+ self.addCleanup(temp.cleanup)
+ self.directory = Path(temp.name)
+ self.output = self.directory / "selection.json"
+ self.assets = self.csv("assets", ASSET, DEVICE)
+
+ def csv(self, name, *rows):
+ path = self.directory / (name + ".csv")
+ with path.open("w", encoding="utf-8", newline="") as stream:
+ writer = csv.DictWriter(stream, fieldnames=rows[0])
+ writer.writeheader()
+ writer.writerows(rows)
+ return path
+
+ def capture(self, *chunks_and_flags, error=None):
+ args = [
+ sys.executable,
+ CAPTURE,
+ "--assets",
+ self.assets,
+ "--asset-id",
+ ASSET_ID,
+ "--repository-url",
+ URL,
+ "--output",
+ self.output,
+ "--findings",
+ *chunks_and_flags,
+ ]
+ result = subprocess.run(args, capture_output=True, text=True, check=False)
+ if error is not None:
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn(error, result.stderr)
+ return None
+ self.assertEqual(result.returncode, 0, result.stderr)
+ return json.loads(self.output.read_text())
+
+ def test_selected_fields_and_case_sensitive_ids_across_chunks(self):
+ # The description exceeds csv's default field limit and includes quoted CSV syntax.
+ description = "x" * 131072 + ' "two lines",\nand a comma.'
+ evidence = {"description": description, "solution": "Use the existing guard."}
+ first = {**FINDING, **evidence, "src": "lib/example.py", "pos": "7", "other": "ignored"}
+ second = {**first, "finding_id": "demo:0001", "src": "", "pos": ""}
+ result = self.capture(self.csv("first", first), self.csv("second", second), *LOCATIONS)
+ self.assertEqual(
+ result,
+ {
+ "format": "tenable-one-code-repository/v1",
+ "asset": ASSET,
+ "repository_url": URL,
+ "findings": [
+ {
+ **FINDING,
+ **evidence,
+ "code_file_path": "lib/example.py",
+ "code_line_number": 7,
+ },
+ {**FINDING, **evidence, "finding_id": "demo:0001"},
+ ],
+ },
+ )
+
+ def test_default_vendor_headers_without_mapped_locations(self):
+ row = {
+ "asset_id": ASSET_ID,
+ "finding_id": FINDING["finding_id"],
+ "state": FINDING["state"],
+ "finding_detection_name": FINDING["finding_name"],
+ "finding_severity": FINDING["severity"],
+ "finding_solution": "Fix",
+ "finding_description": "Details",
+ "code_file_path": "ignored.py",
+ "code_line_number": "9",
+ }
+ result = self.capture(self.csv("chunk", row))
+ self.assertEqual(
+ result["findings"], [{**FINDING, "solution": "Fix", "description": "Details"}]
+ )
+
+ def test_header_only_export(self):
+ chunk = self.directory / "empty.csv"
+ chunk.write_text("asset_id,finding_id,finding_detection_name,finding_severity,state\n")
+ self.assertEqual(self.capture(chunk)["findings"], [])
+
+ def test_mixed_assets_duplicate_ids_and_inconsistent_or_missing_headers(self):
+ first = self.csv("first", FINDING)
+ for row, error in [
+ ({**FINDING, "asset_id": OTHER_ID}, "different or missing asset_id"),
+ ({**FINDING, "finding_name": "Conflicting title"}, "duplicate finding_id"),
+ ({**FINDING, "extra": "value"}, "column names or order differ"),
+ ({k: v for k, v in FINDING.items() if k != "state"}, "missing CSV columns"),
+ ]:
+ with self.subTest(error=error):
+ self.capture(first, self.csv("second", row), error=error)
+ self.assertFalse(self.output.exists())
+ self.capture(first, "--path-column", "not_exported", error="missing CSV columns")
+
+ def test_asset_selection_requires_one_matching_repository(self):
+ chunk = self.csv("chunk", FINDING)
+ for rows, error in [
+ ([DEVICE], "not found"),
+ ([ASSET, ASSET], "multiple inventory rows"),
+ ([{**ASSET, "asset_class": "DEVICE"}], "must have asset_class CODE_REPOSITORY"),
+ ]:
+ with self.subTest(error=error):
+ self.assets = self.csv("assets", *rows)
+ self.capture(chunk, error=error)
+ self.assertFalse(self.output.exists())
+
+ def test_zero_line_number_keeps_an_optional_path(self):
+ first = {**FINDING, "src": "lib/example.py", "pos": "0"}
+ second = {**first, "finding_id": "Demo:0002", "src": ""}
+ result = self.capture(self.csv("chunk", first, second), *LOCATIONS)
+ self.assertEqual(
+ result["findings"],
+ [
+ {**FINDING, "code_file_path": first["src"]},
+ {**FINDING, "finding_id": "Demo:0002"},
+ ],
+ )
+
+ def test_invalid_line_number_is_rejected(self):
+ for line in ("-1", "3.5", "line twelve"):
+ with self.subTest(line=line):
+ chunk = self.csv("chunk", {**FINDING, "src": "lib/example.py", "pos": line})
+ self.capture(chunk, *LOCATIONS, error="must be a nonnegative integer")
+
+ def test_existing_output_is_preserved(self):
+ self.output.write_bytes(b"previous")
+ self.capture(self.csv("chunk", FINDING), error="selection.json")
+ self.assertEqual(self.output.read_bytes(), b"previous")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/examples/tenable-one/test_download.py b/examples/tenable-one/test_download.py
new file mode 100644
index 000000000..85de130c4
--- /dev/null
+++ b/examples/tenable-one/test_download.py
@@ -0,0 +1,161 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, call, patch
+from urllib.parse import parse_qs, urlsplit
+
+from download import download, tenable_request
+
+EXPORT = "/api/v1/t1/inventory/export"
+ASSET = "6e51b7ca-7ca3-48d0-990f-65a86af6b9c8"
+FIRST = "8a907774-2830-44f8-98ff-530a128ca621"
+SECOND = "ab55b579-f403-48f7-a459-87fb541dc4fb"
+URL = "https://example.org/example/repo"
+ASSET_EXPORT = (
+ f"asset_id,asset_name,asset_class\r\n{ASSET},example/repo,CODE_REPOSITORY\r\n".encode()
+)
+HEADERS = b"finding_id,finding_name,asset_id,state,finding_severity,finding_description,finding_solution,file_path,code_line_number\r\n"
+
+
+def finding(finding_id, asset=ASSET):
+ return f"{finding_id},Sample finding,{asset},ACTIVE,HIGH,Details,Fix,src/main.py,7\r\n".encode()
+
+
+def export(job, *chunks, state="FINISHED"):
+ # POST, two status polls, then one GET per returned chunk.
+ return [
+ json.dumps({"export_id": job}),
+ json.dumps({"export_id": job, "status": "PROCESSING"}),
+ json.dumps(
+ {"export_id": job, "status": state, "chunks_available": list(range(len(chunks)))}
+ ),
+ *chunks,
+ ]
+
+
+class DownloadTests(unittest.TestCase):
+ def setUp(self):
+ temp = tempfile.TemporaryDirectory()
+ self.addCleanup(temp.cleanup)
+ self.output = Path(temp.name) / "selection.json"
+ self.request = Mock()
+ self.sleep = Mock()
+
+ def run_download(self, *responses, ids=(FIRST,)):
+ self.request.side_effect = responses
+ download(ASSET, ids, URL, self.output, self.request, self.sleep)
+
+ def test_scoped_exports_poll_and_read_all_chunks(self):
+ # Give each job an ID distinct from its requested asset or finding ID.
+ self.run_download(
+ *export(FIRST, ASSET_EXPORT),
+ *export(SECOND, HEADERS, HEADERS + finding(FIRST)),
+ *export(ASSET, HEADERS + finding(SECOND)),
+ ids=(FIRST, SECOND),
+ )
+ requests = iter(self.request.call_args_list)
+ for kind, selected, job, header, count in [
+ ("assets", ASSET, FIRST, ASSET_EXPORT.splitlines()[0], 1),
+ ("findings", FIRST, SECOND, HEADERS, 2),
+ ("findings", SECOND, ASSET, HEADERS, 1),
+ ]:
+ method, path, payload = next(requests).args
+ endpoint = urlsplit(path)
+ self.assertEqual((method, endpoint.path), ("POST", f"{EXPORT}/{kind}"))
+ query = parse_qs(endpoint.query)
+ self.assertEqual(query["file_format"], ["CSV"])
+ self.assertEqual(query["use_readable_name"], ["false"])
+ self.assertCountEqual(
+ query["properties"][0].split(","), header.decode().strip().split(",")
+ )
+ field = "asset_id" if kind == "assets" else "finding_id"
+ self.assertEqual(
+ payload["filters"], [{"property": field, "operator": "=", "value": [selected]}]
+ )
+ prefix = f"{EXPORT}/{job}"
+ for suffix in ["status", "status", *(f"download/{i}" for i in range(count))]:
+ self.assertEqual(next(requests), call("GET", f"{prefix}/{suffix}"))
+ self.assertIsNone(next(requests, None))
+ self.assertEqual(self.sleep.call_count, 3)
+ result = json.loads(self.output.read_text())
+ self.assertEqual(result["asset"]["asset_id"], ASSET)
+ self.assertEqual(result["repository_url"], URL)
+ self.assertEqual([r["finding_id"] for r in result["findings"]], [FIRST, SECOND])
+ for row in result["findings"]:
+ self.assertEqual((row["code_file_path"], row["code_line_number"]), ("src/main.py", 7))
+
+ def test_unexpected_export_rows_are_rejected_atomically(self):
+ for data in (b"", finding(SECOND), finding(FIRST) * 2, finding(FIRST, asset=SECOND)):
+ with self.subTest(data=data), self.assertRaises(ValueError):
+ self.run_download(*export(FIRST, ASSET_EXPORT), *export(SECOND, HEADERS + data))
+ self.assertFalse(self.output.exists())
+ mixed = ASSET_EXPORT + f"{SECOND},example/other,CODE_REPOSITORY\r\n".encode()
+ with self.assertRaisesRegex(ValueError, "unrequested asset"):
+ self.run_download(*export(FIRST, mixed))
+ self.assertFalse(self.output.exists())
+
+ def test_job_error_leaves_no_artifact(self):
+ with self.assertRaisesRegex(ValueError, "ERROR"):
+ self.run_download(*export(FIRST, state="ERROR"))
+ self.assertFalse(self.output.exists())
+
+ def test_invalid_selection_fails_before_queueing(self):
+ for ids in ([], [FIRST, FIRST]):
+ with self.subTest(ids=ids), self.assertRaises(ValueError):
+ self.run_download(ids=ids)
+ self.output.write_bytes(b"previous")
+ with self.assertRaises(FileExistsError):
+ self.run_download()
+ self.assertEqual(self.output.read_bytes(), b"previous")
+ self.request.assert_not_called()
+
+ def test_invalid_credentials_never_appear_in_diagnostics(self):
+ malformed = "synthetic-private-value\r\nnext-header"
+ for access, secret in ((malformed, "example-secret"), ("example-access", malformed)):
+ with self.subTest(access=access), self.assertRaises(ValueError) as error:
+ tenable_request(access, secret)
+ self.assertNotIn("synthetic-", str(error.exception))
+
+ def test_http_retries_only_pending_chunk_gets_and_never_follows_redirects(self):
+ chunk = f"{EXPORT}/{FIRST}/download/0"
+ status = f"{EXPORT}/{FIRST}/status"
+ for method, path, statuses in [
+ ("GET", chunk, [204, 204, 200]),
+ ("GET", chunk, [204] * 5),
+ ("GET", status, [204]),
+ ("POST", f"{EXPORT}/assets", [204]),
+ ("GET", status, [302]),
+ ]:
+ with (
+ self.subTest(statuses=statuses, path=path),
+ patch("download.time.sleep") as sleep,
+ patch("download.http.client.HTTPSConnection") as connect,
+ ):
+ responses = [Mock(status=code) for code in statuses]
+ responses[-1].read.return_value = b"ready"
+ responses[-1].getheader.return_value = "https://other.example.org/redirect"
+ connection = connect.return_value
+ connection.getresponse.side_effect = responses
+ request = tenable_request("example-access", "example-secret")
+ if statuses[-1] == 200:
+ self.assertEqual(request(method, path), b"ready")
+ else:
+ with self.assertRaisesRegex(ValueError, str(statuses[-1])):
+ request(method, path)
+ self.assertEqual(connect.call_count, len(statuses))
+ for origin in connect.call_args_list:
+ self.assertEqual(origin.args, ("cloud.tenable.com",))
+ self.assertGreater(origin.kwargs["timeout"], 0)
+ for attempt in connection.request.call_args_list:
+ self.assertEqual(attempt.args, (method, path))
+ self.assertEqual(
+ attempt.kwargs["headers"]["X-ApiKeys"],
+ "accessKey=example-access;secretKey=example-secret",
+ )
+ self.assertEqual(connection.close.call_count, len(statuses))
+ self.assertEqual(sleep.call_count, len(statuses) - 1)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index fbd2299bd..d98492299 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1414,6 +1414,8 @@ codex-security publish findings /private/path/endor-findings.json --provider end
After reviewing the findings and exclusions, rerun the command without
`--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
+For Tenable One Code Repository findings, use `--provider tenable --to local` and set `--source-repository-url` to the checkout’s verified HTTPS remote. [Tenable export and import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/tenable.md)
+
Local readback uses `findings imported [PATH]`. The path defaults to the current
directory. Each imported record starts as `not_assessed`. Unknown revisions and
locations stay unknown. Repository-scoped sources are checked against comparable
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index 42f739287..45a3acb26 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -67,6 +67,7 @@ const distModules = [
"blackduck-findings",
"wiz-csv",
"veracode-findings",
+ "tenable-findings",
"wiz-findings",
"codex-prompt",
"codex-sdk-environment",
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 7e1bf18de..0570f19cb 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -136,6 +136,7 @@ import { prepareSonarImport } from "./sonar-import.js";
import {
EXTERNAL_FINDINGS_PROVIDERS,
EXTERNAL_FINDINGS_READERS,
+ requireCloudReader,
} from "./external-findings-read.js";
import {
externalImportDisposition,
@@ -3848,7 +3849,7 @@ export async function main(
provider: z
.enum(EXTERNAL_FINDINGS_READERS)
.describe(
- "Select the file reader for this report. OpenGrep findings use the semgrep storage provider.",
+ "Select the file reader for this report. OpenGrep findings use the semgrep storage provider. Tenable requires --to local and --source-repository-url.",
),
sourceRepositoryUrl: optionValue("--source-repository-url")
.optional()
@@ -4050,6 +4051,7 @@ export async function main(
else if (!structured) writeDiagnostic(summary);
return { ...result };
}
+ requireCloudReader(publicationOptions);
const prepared = await prepareExternalPublication(
report,
publicationOptions,
diff --git a/sdk/typescript/src/external-findings-import.ts b/sdk/typescript/src/external-findings-import.ts
index 2180eabdc..eba61b420 100644
--- a/sdk/typescript/src/external-findings-import.ts
+++ b/sdk/typescript/src/external-findings-import.ts
@@ -1,16 +1,17 @@
-import type { ExternalPublicationOptions } from "./external-findings-publish.js";
import {
cloudRepositoryUrlKey,
repositoryUrlKey,
} from "./external-import-contract.js";
import {
EXTERNAL_FINDINGS_PROVIDERS,
+ type ExternalFindingsReaderOptions,
readExternalFindings,
} from "./external-findings-read.js";
import {
distinctSourceRepositories,
prepareLocalImport,
type LocalExternalImportDependencies,
+ type NormalizedLocalImportOptions,
} from "./external-findings-local.js";
import {
snapshotImportOptions,
@@ -19,10 +20,15 @@ import {
import { abortable } from "./targets.js";
import { requireExternalImports } from "./external-imports-feature.js";
+export interface LocalExternalImportOptions
+ extends
+ Omit<NormalizedLocalImportOptions, "provider">,
+ ExternalFindingsReaderOptions {}
+
/** Read an installed vendor format and prepare it for the local workbench. */
export async function prepareLocalExternalImport(
path: string,
- options: ExternalPublicationOptions,
+ options: LocalExternalImportOptions,
dependencies: LocalExternalImportDependencies = {},
) {
dependencies.signal?.throwIfAborted();
diff --git a/sdk/typescript/src/external-findings-local.ts b/sdk/typescript/src/external-findings-local.ts
index feb505c09..777a01756 100644
--- a/sdk/typescript/src/external-findings-local.ts
+++ b/sdk/typescript/src/external-findings-local.ts
@@ -48,7 +48,12 @@ import type {
import {
localFindingRepositories,
semgrepSarifRepositories,
+ type LocalFindingProvider,
} from "./external-findings-read.js";
+import {
+ tenableReportFormat,
+ tenableSourceRepository,
+} from "./tenable-findings.js";
import {
guardianFindingSourceData,
guardianSelectionFormat,
@@ -103,7 +108,7 @@ import {
export interface StoredExternalFinding {
id: string;
repository: string;
- provider: Provider;
+ provider: LocalFindingProvider;
sourceKey: string;
sourceFindingId: string;
evidence: ExternalFindingEvidence;
@@ -116,10 +121,10 @@ export interface StoredExternalFinding {
export interface NormalizedLocalImportOptions {
/** Local checkout or source directory to associate with these records. */
repository: string;
- provider: Provider;
+ provider: LocalFindingProvider;
/** Stable scanner organization/project/branch namespace across imports. */
sourceKey: string;
- /** Explicitly verified Sonar repository when a checkout uses an SSH host alias. */
+ /** Verified Git repository URL for readers that bind a finding to a checkout. */
sourceRepositoryUrl?: string;
/** Full Inspector project ARNs mapped to independently verified repository URLs. */
inspectorProjectMap?: ReadonlyMap<string, string>;
@@ -135,7 +140,7 @@ export interface LocalExternalImportDependencies {
export interface LocalExternalImportPreview extends ExternalFindings {
repository: string;
- source: { provider: Provider; source_key: string };
+ source: { provider: LocalFindingProvider; source_key: string };
}
export interface LocalExternalImportResult {
@@ -745,7 +750,8 @@ export function distinctSourceRepositories(
/** @internal Prepare evidence using settings captured by either local import entrypoint. */
export async function prepareLocalImport(
input: ExternalFindings & Partial<SnykIssuesFindings>,
- options: NormalizedLocalImportOptions & { sourceRepositoryUrl?: string },
+ options: NormalizedLocalImportOptions &
+ ({ provider: "tenable" } | { provider: Provider }),
dependencies: LocalExternalImportDependencies,
readerSources = distinctSourceRepositories(
snapshotSourceRepositories(dependencies.sourceRepositories),
@@ -756,6 +762,16 @@ export async function prepareLocalImport(
requireIdentity(options.sourceKey, "Source key");
const parsedSources = distinctSourceRepositories(parsedInput);
const current = snapshotNormalizedFindings(input, checkStoredNumber);
+ if (
+ options.provider !== "tenable" &&
+ (current.report?.["format"] === tenableReportFormat ||
+ current.findings.some(
+ (row) => row.evidence?.source_data?.["format"] === tenableReportFormat,
+ ))
+ )
+ throw new CodexSecurityError(
+ "Retained Tenable evidence requires the tenable provider.",
+ );
checkTrivyReportProvider(options.provider, current.report);
// The JSON snapshot omits inherited or non-enumerable SDK reader properties.
if (!("snykRestContext" in current) && "snykRestContext" in input)
@@ -797,10 +813,32 @@ export async function prepareLocalImport(
);
dependabotSource = native;
}
- const { repository, options: workbenchOptions } = await localContext(
- options.repository,
- dependencies,
- );
+ const context = await localContext(options.repository, dependencies);
+ if (options.provider === "tenable") {
+ const source = tenableSourceRepository(
+ current,
+ options.sourceRepositoryUrl,
+ [...readerSources, ...parsedSources],
+ );
+ const remotes = await readHostedGitRemotes(
+ context.repository,
+ [
+ ...context.options.protectedRoot,
+ await abortable(
+ () => canonicalConfigPath(process.cwd()),
+ dependencies.signal,
+ ),
+ ],
+ context.options.environment,
+ dependencies.signal,
+ );
+ if (!remotes?.some((remote) => hostedRepositoryMatches(source, remote)))
+ throw new CodexSecurityError(
+ "Tenable's source repository must match a configured Git fetch remote of the selected checkout.",
+ );
+ return preparedLocalStorage(current, options, context, dependencies, true);
+ }
+ const { repository, options: workbenchOptions } = context;
const sources = new Map<string, ExternalSourceRepository>();
const references = [...readerSources, ...parsedSources];
const inspector = inspectorReportRepository(
@@ -1299,6 +1337,25 @@ export async function prepareLocalImport(
? (url) => checkmarxKeys.has(identify(url).key)
: undefined,
);
+ return preparedLocalStorage(
+ current,
+ options,
+ context,
+ dependencies,
+ matchesRepositoryRemote,
+ );
+}
+
+function preparedLocalStorage(
+ current: ExternalFindings,
+ options: NormalizedLocalImportOptions,
+ {
+ repository,
+ options: workbenchOptions,
+ }: Awaited<ReturnType<typeof localContext>>,
+ dependencies: LocalExternalImportDependencies,
+ matchesRepositoryRemote: boolean,
+): PreparedLocalExternalImport {
dependencies.signal?.throwIfAborted();
const preview = {
...cloneImportPreview(current),
diff --git a/sdk/typescript/src/external-findings-publish.ts b/sdk/typescript/src/external-findings-publish.ts
index 7a1299164..ad34f9020 100644
--- a/sdk/typescript/src/external-findings-publish.ts
+++ b/sdk/typescript/src/external-findings-publish.ts
@@ -29,6 +29,8 @@ import {
type PrivateImportJob,
} from "./private-finding-import.js";
import { readCloudCredentials } from "./cloud-publish.js";
+import type { LocalExternalImportOptions } from "./external-findings-import.js";
+import { tenableReportFormat } from "./tenable-findings.js";
import {
guardianFindingId,
guardianSelectionFormat,
@@ -48,8 +50,9 @@ import {
import {
EXTERNAL_FINDINGS_PROVIDERS,
readExternalFindings,
+ requireCloudReader,
semgrepSarifRepositories,
- type ExternalFindingsReaderOptions,
+ type CloudFindingsReader,
} from "./external-findings-read.js";
import {
canSnapshotWithoutGetters,
@@ -159,11 +162,10 @@ export interface NormalizedExternalPublicationOptions {
inspectorProjectMap?: ReadonlyMap<string, string>;
}
-/** File readers accept the vendor formats installed in this SDK. */
-export interface ExternalPublicationOptions
- extends
- Omit<NormalizedExternalPublicationOptions, "provider">,
- ExternalFindingsReaderOptions {}
+/** File readers accepted by the Cloud publisher. */
+export interface ExternalPublicationOptions extends LocalExternalImportOptions {
+ provider: CloudFindingsReader;
+}
/** Optional transport, account, cancellation, and progress hooks. */
export interface ExternalPublicationDependencies {
@@ -582,19 +584,23 @@ function storedFindingId(finding: ExternalFinding): string {
return "";
}
-function rejectGuardianSelection(input: ExternalFindings): void {
- const isGuardian = (row: ExternalFinding) =>
- row &&
- (guardianFindingId.test(storedFindingId(row)) ||
- ownData(ownData(row.evidence, "source_data"), "format") ===
- guardianSelectionFormat);
- if (
- ownData(ownData(input, "report"), "format") === guardianSelectionFormat ||
- (Array.isArray(input?.findings) && input.findings.some(isGuardian))
- )
- throw new CodexSecurityError(
- "Semgrep Guardian findings require a local import.",
- );
+function rejectLocalOnlyFindings(input: ExternalFindings): void {
+ function checkFormat(format: unknown) {
+ if (format === tenableReportFormat)
+ requireCloudReader({ provider: "tenable" });
+ if (format === guardianSelectionFormat)
+ throw new CodexSecurityError(
+ "Semgrep Guardian findings require a local import.",
+ );
+ }
+ checkFormat(ownData(ownData(input, "report"), "format"));
+ if (!Array.isArray(input?.findings)) return;
+ for (const row of input.findings) {
+ if (!row) continue;
+ if (guardianFindingId.test(storedFindingId(row)))
+ checkFormat(guardianSelectionFormat);
+ checkFormat(ownData(ownData(row.evidence, "source_data"), "format"));
+ }
}
export async function prepareExternalPublication(
@@ -604,6 +610,7 @@ export async function prepareExternalPublication(
): Promise<PreparedExternalPublication> {
requireExternalImports(dependencies.environment);
const settings = snapshotImportOptions(options);
+ requireCloudReader(settings);
const readerSources = snapshotSourceRepositories(
dependencies.sourceRepositories,
);
@@ -674,7 +681,7 @@ export async function prepareExternalPublication(
: await normalize();
} else {
const parsed = await readExternalFindings(path, settings);
- rejectGuardianSelection(parsed.findings);
+ rejectLocalOnlyFindings(parsed.findings);
input =
parsed.publication ??
normalizedPublicationInput(parsed.findings, provider);
@@ -698,6 +705,7 @@ export async function prepareNormalizedExternalPublication(
): Promise<PreparedExternalPublication> {
requireExternalImports(dependencies.environment);
const settings = snapshotImportOptions(options);
+ requireCloudReader(settings);
return preparePublicationInput(
normalizedPublicationInput(input, settings.provider),
settings,
@@ -1191,7 +1199,7 @@ function normalizedPublicationInput(
: undefined;
if (reader) native = reader.snapshot;
const original = historicalPublication(native);
- if (original) rejectGuardianSelection(original.parsed);
+ if (original) rejectLocalOnlyFindings(original.parsed);
try {
validatePublicationFindings(current, validateExternalEvidence);
} catch (error) {
@@ -1204,7 +1212,7 @@ function normalizedPublicationInput(
// Only the old selection can be reviewed when fresh validation failed.
current = { read: original.parsed.read, findings: [], excluded: [] };
}
- rejectGuardianSelection(current);
+ rejectLocalOnlyFindings(current);
// A Trivy header provides repository provenance for its findings. Either entrypoint
// can resume the same immutable request when the independently checked rows agree.
const identity =
@@ -2084,7 +2092,7 @@ async function preparePublicationInput(
!verifiableLegacyMetadata(originalParsed, true)
)
throw unmatchedPreviousNumbers();
- rejectGuardianSelection({ ...parsed, findings: saved });
+ rejectLocalOnlyFindings({ ...parsed, findings: saved });
const approvedScope = content.inputProjection?.semgrepPartialScopeDigest;
if (
approvedScope !== undefined &&
@@ -2128,7 +2136,7 @@ async function preparePublicationInput(
!verifiableLegacyMetadata(originalParsed, false)
)
throw unmatchedPreviousNumbers();
- rejectGuardianSelection({ ...parsed, findings: saved });
+ rejectLocalOnlyFindings({ ...parsed, findings: saved });
content.legacyApproval = true;
content.inputProjection = {
...content.inputProjection,
diff --git a/sdk/typescript/src/external-findings-read.ts b/sdk/typescript/src/external-findings-read.ts
index b67de2866..38b5ac666 100644
--- a/sdk/typescript/src/external-findings-read.ts
+++ b/sdk/typescript/src/external-findings-read.ts
@@ -7,6 +7,8 @@ import type {
import { hasNoExternalRecords } from "./external-findings.js";
import { readScannerJson, sarifRunRepositories } from "./scanner-import.js";
import type { Provider } from "./external-import-models.js";
+import { CodexSecurityError } from "./errors.js";
+import { readTenableFindings } from "./tenable-findings.js";
import type { ExternalImportTarget } from "./external-import-contract.js";
import { dependabotRepository } from "./github-dependabot-findings.js";
import {
@@ -47,7 +49,9 @@ import {
wizFindingRepository,
} from "./wiz-findings.js";
-/** File reader names mapped to their stored and Cloud source provider. */
+export type LocalFindingProvider = Provider | "tenable";
+
+/** File reader names mapped to the provider stored with each finding. */
export const EXTERNAL_FINDINGS_PROVIDERS = {
wiz: "wiz",
snyk: "snyk",
@@ -63,15 +67,28 @@ export const EXTERNAL_FINDINGS_PROVIDERS = {
sonar: "sonar",
continuum: "continuum",
checkmarx: "checkmarx",
-} as const satisfies Record<string, Provider>;
+ tenable: "tenable",
+} as const satisfies Record<string, LocalFindingProvider>;
export type ExternalFindingsReader = keyof typeof EXTERNAL_FINDINGS_PROVIDERS;
+export type CloudFindingsReader = Exclude<ExternalFindingsReader, "tenable">;
+
+export function requireCloudReader(
+ options: ExternalFindingsReaderOptions,
+): asserts options is ExternalFindingsReaderOptions & {
+ provider: CloudFindingsReader;
+} {
+ if (options.provider === "tenable")
+ throw new CodexSecurityError(
+ "Tenable findings require a local import (--to local).",
+ );
+}
export const EXTERNAL_FINDINGS_READERS = Object.keys(
EXTERNAL_FINDINGS_PROVIDERS,
) as ExternalFindingsReader[];
-/** File readers available in this SDK, shared by local and Cloud imports. */
+/** File readers available in this SDK. Cloud supports a subset of these readers. */
export interface ExternalFindingsReaderOptions {
provider: ExternalFindingsReader;
sourceRepositoryUrl?: string;
@@ -172,6 +189,15 @@ export async function readExternalFindings(
references: readonly ExternalSourceRepository[] = [],
): Promise<ReadExternalFindings> {
const { provider } = options;
+ if (provider === "tenable") {
+ if (target === "cloud") requireCloudReader(options);
+ return {
+ findings: await readTenableFindings(
+ path,
+ options.sourceRepositoryUrl ?? "",
+ ),
+ };
+ }
if (provider === "trivy")
return {
findings: await readTrivyFindings(path, target, options.trivyScanRoot),
diff --git a/sdk/typescript/src/external-findings.ts b/sdk/typescript/src/external-findings.ts
index 8ad933ab3..eb8410865 100644
--- a/sdk/typescript/src/external-findings.ts
+++ b/sdk/typescript/src/external-findings.ts
@@ -1,6 +1,6 @@
import { isNativeError, isNumberObject } from "node:util/types";
import { CodexSecurityError } from "./errors.js";
-import type { ExternalPublicationOptions } from "./external-findings-publish.js";
+import type { LocalExternalImportOptions } from "./external-findings-import.js";
import {
checkEmittedJsonNumber,
checkReportNumber,
@@ -217,7 +217,7 @@ export interface ExternalPublicationInput {
/** Capture the caller's import settings before reading an export or resolving its destination. */
export function snapshotImportOptions<
- P extends ExternalPublicationOptions["provider"],
+ P extends LocalExternalImportOptions["provider"],
>({
repository,
provider,
@@ -225,7 +225,7 @@ export function snapshotImportOptions<
sourceRepositoryUrl,
trivyScanRoot,
inspectorProjectMap,
-}: ExternalPublicationOptions & { provider: P }) {
+}: LocalExternalImportOptions & { provider: P }) {
if (provider === "trivy" && sourceRepositoryUrl !== undefined)
throw new CodexSecurityError(
"Trivy reads repository provenance from the report; do not supply --source-repository-url.",
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index c7a4c9d57..29f6060ac 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -347,7 +347,11 @@ export type {
OperationFailureCategory,
} from "./operation-telemetry.js";
-export { prepareLocalExternalImport } from "./external-findings-import.js";
+export {
+ prepareLocalExternalImport,
+ type LocalExternalImportOptions,
+} from "./external-findings-import.js";
+export { readTenableFindings } from "./tenable-findings.js";
export {
normalizeOpenGrepFindings,
readOpenGrepFindings,
diff --git a/sdk/typescript/src/tenable-findings.ts b/sdk/typescript/src/tenable-findings.ts
new file mode 100644
index 000000000..6570e1646
--- /dev/null
+++ b/sdk/typescript/src/tenable-findings.ts
@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { CodexSecurityError } from "./errors.js";
+import { asRecord } from "./record.js";
+import { isGitHubCloudHost } from "./git-remote.js";
+import type {
+ ExternalFindings,
+ ExternalSourceRepository,
+} from "./external-findings.js";
+import {
+ repositoryUrlKey,
+ validateExternalEvidence,
+} from "./external-import-contract.js";
+import {
+ readScannerJson,
+ repositoryFilePath,
+ scannerSeverity,
+} from "./scanner-import.js";
+import { declaredScannerRepositoryUrl } from "./scanner-repository-url.js";
+
+export const tenableReportFormat = "tenable-one-code-repository/v1";
+
+// The capture joins inventory exports on asset_id and records the operator's SCM binding.
+const nonblank = z.string().regex(/\S/u);
+const assetId = z.guid().toLowerCase();
+const selection = z.object({
+ format: z.literal(tenableReportFormat),
+ asset: z.object({
+ asset_class: z.literal("CODE_REPOSITORY"),
+ asset_id: assetId,
+ asset_name: nonblank,
+ }),
+ repository_url: nonblank,
+ findings: z.array(
+ z.object({
+ asset_id: assetId,
+ finding_id: nonblank,
+ finding_name: nonblank,
+ severity: nonblank,
+ state: nonblank,
+ description: z.string().optional(),
+ solution: z.string().optional(),
+ code_file_path: nonblank.optional(),
+ code_line_number: z
+ .union([z.int().positive(), z.string().regex(/^\d+$/u)])
+ .optional(),
+ }),
+ ),
+});
+
+function findingLocations(rawPath?: string, rawLine?: number | string) {
+ if (rawPath === undefined && rawLine === undefined) return [];
+ const path = repositoryFilePath(rawPath);
+ if (!path)
+ throw new Error(
+ "Tenable code locations require a repository-relative file path.",
+ );
+ const line = rawLine === undefined ? null : Number(rawLine);
+ if (line !== null && (!Number.isSafeInteger(line) || line < 1))
+ throw new Error("Tenable code line number must be a positive integer.");
+ return [{ path, line }];
+}
+
+function assertRepository(claim: unknown, expected: string) {
+ const url = declaredScannerRepositoryUrl(claim, "Tenable", "local");
+ if (repositoryUrlKey(url) !== repositoryUrlKey(expected))
+ throw new CodexSecurityError(
+ "Tenable repository URL does not match --source-repository-url.",
+ );
+ return url;
+}
+
+/** Verify retained identities when importing a normalized selection through the SDK. */
+export function tenableSourceRepository(
+ input: ExternalFindings,
+ declared: string | undefined,
+ references: readonly ExternalSourceRepository[],
+) {
+ const url = declaredScannerRepositoryUrl(declared, "Tenable", "local");
+ const asset = asRecord(input.report?.["asset"]);
+ if (
+ input.report?.["format"] !== tenableReportFormat ||
+ asset?.["asset_class"] !== "CODE_REPOSITORY" ||
+ !nonblank.safeParse(asset["asset_id"]).success
+ )
+ throw new CodexSecurityError(
+ "Tenable imports require a report for one code repository asset.",
+ );
+ assertRepository(input.report["repositoryUrl"], url);
+ for (const ref of references) assertRepository(ref.url, url);
+ for (const { source_finding_id, evidence } of input.findings) {
+ validateExternalEvidence(evidence, "local");
+ const data = evidence.source_data;
+ const rowAsset = asRecord(data?.["asset"]);
+ const finding = asRecord(data?.["finding"]);
+ if (
+ data?.["format"] !== tenableReportFormat ||
+ rowAsset?.["asset_class"] !== asset["asset_class"] ||
+ rowAsset["asset_id"] !== asset["asset_id"] ||
+ finding?.["asset_id"] !== asset["asset_id"] ||
+ finding?.["finding_id"] !== source_finding_id
+ )
+ throw new CodexSecurityError(
+ "Tenable findings must retain their native finding ID and one code repository asset.",
+ );
+ assertRepository(data["repository_url"], url);
+ if (evidence.details?.repository?.url !== undefined)
+ assertRepository(evidence.details.repository.url, url);
+ }
+ const { hostname } = new URL(url);
+ return {
+ url,
+ platform: isGitHubCloudHost(hostname)
+ ? "github"
+ : hostname === "gitlab.com"
+ ? "gitlab"
+ : undefined,
+ };
+}
+
+export async function readTenableFindings(
+ path: string,
+ sourceRepositoryUrl: string,
+): Promise<ExternalFindings> {
+ const declared = declaredScannerRepositoryUrl(
+ sourceRepositoryUrl,
+ "Tenable",
+ "local",
+ );
+ const {
+ asset,
+ repository_url,
+ findings: rows,
+ } = selection.parse(await readScannerJson(path));
+ const repository = assertRepository(repository_url, declared);
+ const ids = new Set<string>();
+ const findings = rows.map((finding) => {
+ if (finding.asset_id !== asset.asset_id)
+ throw new Error(
+ "Every Tenable finding must belong to the selected Code Repository asset.",
+ );
+ if (ids.has(finding.finding_id))
+ throw new Error(`Duplicate Tenable finding ID: ${finding.finding_id}`);
+ ids.add(finding.finding_id);
+ const severity = finding.severity.trim().toLowerCase();
+ return {
+ source_finding_id: finding.finding_id,
+ evidence: validateExternalEvidence(
+ {
+ title: finding.finding_name,
+ severity: scannerSeverity(
+ severity === "info" ? "informational" : severity,
+ ),
+ description: finding.description,
+ locations: findingLocations(
+ finding.code_file_path,
+ finding.code_line_number,
+ ),
+ source_data: {
+ format: tenableReportFormat,
+ repository_url,
+ asset,
+ finding,
+ },
+ },
+ "local",
+ ),
+ };
+ });
+ return {
+ read: rows.length,
+ report: { format: tenableReportFormat, repositoryUrl: repository, asset },
+ findings,
+ excluded: [],
+ };
+}
diff --git a/sdk/typescript/src/trivy-import.ts b/sdk/typescript/src/trivy-import.ts
index 94c18df5f..8287a945a 100644
--- a/sdk/typescript/src/trivy-import.ts
+++ b/sdk/typescript/src/trivy-import.ts
@@ -6,7 +6,7 @@ import type {
ExternalSourceRepository,
} from "./external-findings.js";
import type { ExternalImportTarget } from "./external-import-contract.js";
-import type { Provider } from "./external-import-models.js";
+import type { LocalFindingProvider } from "./external-findings-read.js";
import { readHostedGitRemotes } from "./hosted-git-remotes.js";
import { hasGitMetadata } from "./local-git-metadata.js";
import { isRecord } from "./record.js";
@@ -147,7 +147,7 @@ function isRetainedTrivyFinding(finding: ExternalFinding) {
/** Retained rows keep their scanner identity even if the report header is projected out. */
export function checkRetainedTrivyProvider(
- provider: Provider,
+ provider: LocalFindingProvider,
finding: ExternalFinding,
target: ExternalImportTarget = "cloud",
): void {
@@ -162,7 +162,7 @@ export function checkRetainedTrivyProvider(
}
export function checkTrivyReportProvider(
- provider: Provider,
+ provider: LocalFindingProvider,
report: unknown,
): void {
if (provider !== "trivy" && identifiesTrivyReport(report))
diff --git a/sdk/typescript/tests-ts/external-findings-local-helpers.ts b/sdk/typescript/tests-ts/external-findings-local-helpers.ts
index 89c625713..e56374938 100644
--- a/sdk/typescript/tests-ts/external-findings-local-helpers.ts
+++ b/sdk/typescript/tests-ts/external-findings-local-helpers.ts
@@ -1,13 +1,15 @@
import { expect } from "bun:test";
import type { ExternalFindings } from "../src/external-findings.js";
import { EXTERNAL_FINDINGS_PROVIDERS } from "../src/external-findings-read.js";
-import { prepareLocalExternalImport } from "../src/external-findings-import.js";
+import {
+ prepareLocalExternalImport,
+ type LocalExternalImportOptions,
+} from "../src/external-findings-import.js";
import {
listLocalExternalFindings,
prepareNormalizedLocalImport,
type StoredExternalFinding,
} from "../src/external-findings-local.js";
-import type { ExternalPublicationOptions } from "../src/external-findings-publish.js";
import { execFileSync } from "node:child_process";
import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
@@ -66,7 +68,7 @@ export async function localFindingsFixture(options: Checkout = {}) {
export async function localReportFixture(
filename: string,
- source: Omit<ExternalPublicationOptions, "repository">,
+ source: Omit<LocalExternalImportOptions, "repository">,
checkout: Checkout = {},
) {
const fixture = await localFindingsFixture(checkout);
@@ -96,7 +98,7 @@ export async function localReportFixture(
export function isolatedGitReportFixture(
filename: string,
- source: Omit<ExternalPublicationOptions, "repository">,
+ source: Omit<LocalExternalImportOptions, "repository">,
checkout: Checkout = {},
) {
return localReportFixture(filename, source, {
@@ -107,8 +109,13 @@ export function isolatedGitReportFixture(
type LocalReportFixture = Awaited<ReturnType<typeof localReportFixture>>;
-export async function createAndReplayFinding(fixture: LocalReportFixture) {
- const prepared = await fixture.prepare();
+export async function createAndReplayFinding(
+ fixture: LocalReportFixture,
+ normalized?: ExternalFindings,
+) {
+ const prepared = normalized
+ ? await fixture.prepareNormalized(normalized)
+ : await fixture.prepare();
expect(prepared.preview.excluded).toEqual([]);
expect(prepared.preview.findings).toHaveLength(1);
expect(await fixture.read()).toEqual([]);
diff --git a/sdk/typescript/tests-ts/tenable-import.test.ts b/sdk/typescript/tests-ts/tenable-import.test.ts
new file mode 100644
index 000000000..c4a4d4811
--- /dev/null
+++ b/sdk/typescript/tests-ts/tenable-import.test.ts
@@ -0,0 +1,216 @@
+import { expect, mock, test } from "bun:test";
+import { main } from "../src/cli.js";
+import { prepareLocalExternalImport } from "../src/external-findings-import.js";
+import {
+ type NormalizedExternalPublicationOptions,
+ prepareExternalPublication,
+ prepareNormalizedExternalPublication,
+} from "../src/external-findings-publish.js";
+import { readTenableFindings } from "../src/tenable-findings.js";
+import { dependencies as cliDependencies } from "./cli-fixtures.js";
+import {
+ createAndReplayFinding,
+ localReportFixture,
+ updateStoredFinding,
+} from "./external-findings-local-helpers.js";
+import { createCliTest } from "./support/cli-run.js";
+
+const repositoryUrl = "https://github.com/example/repo";
+const asset = {
+ asset_id: "10000000-0000-4000-8000-000000000001",
+ asset_class: "CODE_REPOSITORY",
+ asset_name: "example/repo",
+};
+const row = {
+ asset_id: asset.asset_id,
+ finding_id: "00017",
+ finding_name: "Example finding",
+ severity: "High",
+ state: "ACTIVE",
+};
+const report = {
+ format: "tenable-one-code-repository/v1",
+ asset,
+ repository_url: repositoryUrl,
+ findings: [{ ...row, code_file_path: "src/app.ts", code_line_number: "7" }],
+};
+const source = {
+ provider: "tenable",
+ sourceKey: "example/tenable/code-repository",
+ sourceRepositoryUrl: repositoryUrl,
+} as const;
+
+function checkout() {
+ return localReportFixture("tenable.json", source, {
+ remote: repositoryUrl + ".git",
+ });
+}
+
+test("the reader preserves vendor state and optional severity and locations", async () => {
+ await using fixture = await checkout();
+ await fixture.writeJson({
+ ...report,
+ findings: [
+ { ...row, severity: "INFO", state: "FIXED" },
+ {
+ ...row,
+ finding_id: "00018",
+ severity: "unrated",
+ code_file_path: "src/app.ts",
+ },
+ ],
+ });
+ const { findings } = await readTenableFindings(fixture.file, repositoryUrl);
+ expect(findings[0]!.evidence).toMatchObject({
+ severity: "informational",
+ locations: [],
+ source_data: { finding: { state: "FIXED" } },
+ });
+ expect(findings[1]!.evidence).toMatchObject({
+ severity: "unknown",
+ locations: [{ path: "src/app.ts", line: null }],
+ });
+});
+
+test("the reader rejects ambiguous assets, findings and locations", async () => {
+ await using fixture = await checkout();
+ for (const override of [
+ { asset: { ...asset, asset_class: "DEVICE" } },
+ { findings: [row, row] },
+ {
+ findings: [{ ...row, asset_id: "20000000-0000-4000-8000-000000000002" }],
+ },
+ { findings: [{ ...row, code_file_path: "../unrelated" }] },
+ {
+ findings: [
+ { ...report.findings[0], code_line_number: "9007199254740993" },
+ ],
+ },
+ ]) {
+ await fixture.writeJson({ ...report, ...override });
+ await expect(
+ readTenableFindings(fixture.file, repositoryUrl),
+ ).rejects.toThrow();
+ }
+});
+
+test("the CLI preview can be saved, replayed and updated with its original identity", async () => {
+ await using fixture = await checkout();
+ await fixture.writeJson(report);
+ const cli = createCliTest(main);
+ const code = await cli.runCli(
+ [
+ "publish",
+ "findings",
+ fixture.file,
+ "--provider=tenable",
+ "--to=local",
+ `--repository=${fixture.repository}`,
+ `--source-repository-url=${repositoryUrl}`,
+ `--source-key=${source.sourceKey}`,
+ "--dry-run",
+ "--format=json",
+ ],
+ cliDependencies({ environment: fixture.environment }),
+ );
+ expect(code, cli.stderr.text() || cli.stdout.text()).toBe(0);
+ const preview = JSON.parse(cli.stdout.text());
+ expect(preview.dryRun).toBe(true);
+ expect(preview.source).toEqual({
+ provider: "tenable",
+ source_key: source.sourceKey,
+ });
+ const saved = await createAndReplayFinding(fixture, preview);
+ expect(saved.provider).toBe("tenable");
+ expect(saved.sourceFindingId).toBe(row.finding_id);
+ expect(saved.evidence).toMatchObject({
+ title: row.finding_name,
+ severity: "high",
+ locations: [{ path: "src/app.ts", line: 7 }],
+ });
+ await fixture.writeJson({
+ ...report,
+ findings: [{ ...report.findings[0], finding_name: "Revised finding" }],
+ });
+ expect((await updateStoredFinding(fixture, saved)).evidence.title).toBe(
+ "Revised finding",
+ );
+});
+
+test("file and normalized imports verify repository and finding identity, even for empty selections", async () => {
+ await using fixture = await checkout();
+ await fixture.writeJson(report);
+ await expect(
+ fixture.prepare({ sourceRepositoryUrl: undefined }),
+ ).rejects.toThrow(/repository/i);
+ const otherUrl = "https://github.com/example/other";
+ const { preview } = await fixture.prepare();
+ const wrongReport = structuredClone(preview);
+ wrongReport.report!["repositoryUrl"] = otherUrl;
+ await expect(fixture.prepareNormalized(wrongReport)).rejects.toThrow(
+ /repository/i,
+ );
+ const wrongRow = structuredClone(preview);
+ wrongRow.findings[0]!.evidence.source_data!["repository_url"] = otherUrl;
+ await expect(fixture.prepareNormalized(wrongRow)).rejects.toThrow(
+ /repository/i,
+ );
+ const wrongId = structuredClone(preview);
+ wrongId.findings[0]!.source_finding_id = "17";
+ await expect(fixture.prepareNormalized(wrongId)).rejects.toThrow(
+ /finding ID|identity/i,
+ );
+ fixture.git("remote", "set-url", "origin", otherUrl);
+ for (const findings of [report.findings, []]) {
+ await fixture.writeJson({ ...report, findings });
+ await expect(fixture.prepare()).rejects.toThrow(/remote|checkout/i);
+ }
+ fixture.git("remote", "set-url", "origin", repositoryUrl);
+ const runWorkbench = mock(async () => {
+ throw new Error("Unexpected workbench call");
+ });
+ const empty = await prepareLocalExternalImport(
+ fixture.file,
+ { ...source, repository: fixture.repository },
+ { environment: fixture.environment, runWorkbench },
+ );
+ expect((await empty.import()).counts).toEqual({
+ created: 0,
+ updated: 0,
+ unchanged: 0,
+ });
+ expect(runWorkbench).not.toHaveBeenCalled();
+});
+
+test("local opt-in and Cloud rejection precede file access or credentials", async () => {
+ await using fixture = await checkout();
+ const options = { ...source, repository: fixture.repository };
+ await expect(
+ prepareLocalExternalImport(fixture.file, options, { environment: {} }),
+ ).rejects.toThrow("CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1");
+ const unexpected = mock(async () => {
+ throw new Error("Unexpected Cloud call");
+ });
+ const deps = {
+ environment: fixture.environment,
+ fetch: unexpected,
+ credentials: unexpected,
+ };
+ // JavaScript callers may supply a local provider despite the SDK's Cloud types.
+ const cloudOptions =
+ options as unknown as NormalizedExternalPublicationOptions;
+ const empty = { read: 0, findings: [], excluded: [] };
+ await expect(
+ prepareExternalPublication(fixture.file, cloudOptions, deps),
+ ).rejects.toThrow(/local/i);
+ await expect(
+ prepareNormalizedExternalPublication(empty, cloudOptions, deps),
+ ).rejects.toThrow(/local/i);
+ await fixture.writeJson(report);
+ const { preview } = await fixture.prepare();
+ const relabeled = { ...options, provider: "wiz" as const };
+ await expect(
+ prepareNormalizedExternalPublication(preview, relabeled, deps),
+ ).rejects.toThrow(/local/i);
+ expect(unexpected).not.toHaveBeenCalled();
+});