OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.mdindex 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 endAfter 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 currentdirectory. Each imported record starts as `not_assessed`. Unknown revisions andlocations stay unknown. Repository-scoped sources are checked against comparablediff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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();+});