{"id":51083432,"url":"https://github.com/oabdelmaksoud/safeshift","last_synced_at":"2026-06-23T20:30:46.222Z","repository":{"id":366273872,"uuid":"1275497114","full_name":"oabdelmaksoud/safeshift","owner":"oabdelmaksoud","description":"Open, vendor-neutral shift-left integration-risk prediction for automotive software architectures","archived":false,"fork":false,"pushed_at":"2026-06-21T03:18:51.000Z","size":377,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T05:10:28.978Z","etag":null,"topics":["aspice","automotive","iso-26262","machine-learning","safety-critical","shift-left","software-defined-vehicle"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oabdelmaksoud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T19:10:21.000Z","updated_at":"2026-06-21T03:18:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oabdelmaksoud/safeshift","commit_stats":null,"previous_names":["oabdelmaksoud/safeshift"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/oabdelmaksoud/safeshift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oabdelmaksoud%2Fsafeshift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oabdelmaksoud%2Fsafeshift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oabdelmaksoud%2Fsafeshift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oabdelmaksoud%2Fsafeshift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oabdelmaksoud","download_url":"https://codeload.github.com/oabdelmaksoud/safeshift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oabdelmaksoud%2Fsafeshift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34706578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aspice","automotive","iso-26262","machine-learning","safety-critical","shift-left","software-defined-vehicle"],"created_at":"2026-06-23T20:30:44.005Z","updated_at":"2026-06-23T20:30:46.214Z","avatar_url":"https://github.com/oabdelmaksoud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SafeShift\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20780068.svg)](https://doi.org/10.5281/zenodo.20780068)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)\n\nSafeShift is an open, vendor-neutral toolkit for finding likely integration-risk hotspots in\nautomotive software and E/E architectures before late-stage integration.\n\nIt helps architecture, safety, cybersecurity, and CI teams answer:\n\n\u003e Which interfaces deserve review first, and what evidence should reviewers collect?\n\nSafeShift reads architecture data, builds a dependency graph, scores each interface, and emits\nreview-ready reports, dashboards, SARIF, evidence packs, issue records, and CI workflow artifacts.\n\n```mermaid\nflowchart LR\n    A[\"Architecture sources\"] --\u003e B[\"SafeShift schema\"]\n    B --\u003e C[\"Dependency graph and features\"]\n    C --\u003e D[\"Risk scoring and confidence\"]\n    D --\u003e E[\"Reports, dashboards, SARIF, evidence packs, CI gates\"]\n```\n\n## Contents\n\n- [Why SafeShift Exists](#why-safeshift-exists)\n- [What It Can Do](#what-it-can-do)\n- [Install](#install)\n- [First Run](#first-run)\n- [Quickstart](#quickstart)\n- [Common Workflows](#common-workflows)\n- [Inputs and Outputs](#inputs-and-outputs)\n- [Example Architecture](#example-architecture)\n- [How Scoring Works](#how-scoring-works)\n- [CLI Command Map](#cli-command-map)\n- [Repository Layout](#repository-layout)\n- [Documentation Map](#documentation-map)\n- [Worked Examples](#worked-examples)\n- [Evaluation](#evaluation)\n- [Scope and Limits](#scope-and-limits)\n- [Citation](#citation)\n- [License](#license)\n\n## Why SafeShift Exists\n\nModern vehicles integrate many electronic control units, software modules, suppliers, and tool\nchains. Architecture and integration defects found after physical builds are expensive, slow, and\noften connected to safety, timing, cybersecurity, or supplier-boundary complexity.\n\nSafeShift moves part of that review earlier. It is designed to be:\n\n- **Open**: no proprietary data model or hosted service is required.\n- **Auditable**: reports include feature-level reasons and evidence hooks.\n- **CI-friendly**: outputs include JSON, CSV, HTML, Markdown, and SARIF.\n- **Workflow-oriented**: review state, evidence packs, validation reports, and bundle audits are\n  first-class artifacts.\n\n## What It Can Do\n\n| Capability | What you get |\n| --- | --- |\n| Architecture risk analysis | Ranked LOW/MEDIUM/HIGH integration-risk findings per interface. |\n| Architecture diffing | Added, removed, and changed interfaces with material risk deltas. |\n| Source normalization | YAML/JSON, CSV, mapped tool payloads, generic REST sources, and AUTOSAR ARXML. |\n| Import-quality audits | ARXML, architecture-source, and ingestion-matrix evidence before trusting scores. |\n| Review tracking | Owner, status, decision, mitigation, due date, notes, and evidence references. |\n| AI/ML reviewer assistance | Traceable review-focus and evidence-gap suggestions with provenance, human-review controls, and no default external AI calls. |\n| Standards evidence | Evidence hooks and evidence packs for ASPICE, ISO 26262, ISO/SAE 21434, UNECE R155, and UNECE R156. |\n| Issue handoff | Portable issue records for GitHub, Jira-style APIs, generic HTTP endpoints, or manual boards. |\n| Calibration and validation | Threshold calibration, expert-panel validation, historical-outcome validation, and cohort reports. |\n| CI artifact bundles | Repeatable workflow runs with manifests, dashboards, gates, and readiness audits. |\n| Guided operation | `doctor`, `quickstart`, `wizard`, `open-report`, and a local browser UI for users who do not want to memorize long commands. |\n\n## Install\n\nSafeShift requires Python 3.9 or newer.\n\nFrom the repository root:\n\n```bash\npip install -e .\n```\n\nOptional installs:\n\n```bash\npip install -e \".[ml]\"   # enables the optional RandomForest model\npip install -e \".[dev]\"  # installs test and evaluation dependencies\n```\n\nAfter installation, either command style works:\n\n```bash\npython -m safeshift --help\nsafeshift --help\n```\n\n## First Run\n\nUse the guided path when you want SafeShift to behave like an interface rather than an expert-only\nCLI.\n\nCheck the local setup:\n\n```bash\npython -m safeshift doctor\n```\n\nRun the bundled review workflow and list generated reports:\n\n```bash\npython -m safeshift quickstart --out-dir safeshift-demo\n```\n\nOpen the primary HTML report from that bundle:\n\n```bash\npython -m safeshift open-report safeshift-demo\n```\n\nStart the local browser UI:\n\n```bash\npython -m safeshift ui\n```\n\nThe browser UI lets a user upload or select an architecture file, choose guided review or an\nexisting workflow, run SafeShift, then open or download risk, AI-assist, evidence-gap, model-card,\nand readiness reports. Use `python -m safeshift wizard` for a prompt-driven terminal flow.\n\n## Quickstart\n\nGenerate a self-contained HTML dashboard from the bundled ADAS example:\n\n```bash\npython -m safeshift analyze examples/example_adas_architecture.yaml \\\n  --format html \\\n  --out safeshift-dashboard.html\n```\n\nPrint a Markdown report in the terminal:\n\n```bash\npython -m safeshift analyze examples/example_adas_architecture.yaml\n```\n\nCompare two architecture versions:\n\n```bash\npython -m safeshift diff \\\n  examples/example_adas_architecture.yaml \\\n  examples/example_adas_architecture_update.yaml \\\n  --format html \\\n  --out safeshift-diff.html\n```\n\nRun the full example review workflow:\n\n```bash\npython -m safeshift workflow examples/workflow.yaml --out-dir safeshift-artifacts\n```\n\nRun tests:\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\n## Common Workflows\n\n### 1. Analyze an architecture\n\nUse this for the main risk report.\n\n```bash\npython -m safeshift analyze examples/example_adas_architecture.yaml \\\n  --format markdown \\\n  --out report.md\n```\n\nUseful formats:\n\n- `markdown`: human-readable report.\n- `json`: machine-readable artifact for dashboards and CI.\n- `csv`: spreadsheet-friendly finding export.\n- `html`: self-contained review dashboard.\n- `sarif`: code-scanning and CI integrations.\n\n### 2. Add review state\n\nCreate a review template, fill it in, then include it in later reports.\n\n```bash\npython -m safeshift review-template examples/example_adas_architecture.yaml \\\n  --out review.csv\n\npython -m safeshift analyze examples/example_adas_architecture.yaml \\\n  --review review.csv \\\n  --format html \\\n  --out reviewed-dashboard.html\n```\n\n### 3. Create standards evidence\n\nGenerate a checklist or an aggregated evidence pack for architecture review.\n\n```bash\npython -m safeshift evidence-template examples/example_adas_architecture.yaml \\\n  --out evidence-checklist.csv\n\npython -m safeshift evidence-pack examples/example_adas_architecture.yaml \\\n  --review examples/example_review_state.csv \\\n  --min-band HIGH \\\n  --format html \\\n  --out evidence-pack.html\n```\n\n### 4. Import architecture data from other tools\n\nConvert CSV exports:\n\n```bash\npython -m safeshift import-csv \\\n  --components examples/example_components.csv \\\n  --interfaces examples/example_interfaces.csv \\\n  --name \"CSV ADAS Export\" \\\n  --out csv-architecture.yaml\n```\n\nAnalyze AUTOSAR ARXML directly or convert it first:\n\n```bash\npython -m safeshift analyze examples/example_autosar_annotations.arxml\n\npython -m safeshift import-arxml examples/example_autosar_subset.arxml \\\n  --out arxml-architecture.yaml\n```\n\nAudit an ARXML import before relying on it:\n\n```bash\npython -m safeshift arxml-audit examples/example_autosar_annotations.arxml \\\n  --format html \\\n  --fail-on-audit \\\n  --out arxml-import-audit.html\n```\n\n### 5. Export issues for review handoff\n\n```bash\npython -m safeshift issue-export examples/example_adas_architecture.yaml \\\n  --review examples/example_review_state.csv \\\n  --min-band HIGH \\\n  --format json \\\n  --out safeshift-issues.json\n```\n\nDry-run an issue push plan:\n\n```bash\npython -m safeshift issue-push safeshift-issues.json \\\n  --provider github \\\n  --target owner/repo \\\n  --out issue-push-plan.json\n```\n\n### 6. Calibrate and validate\n\nCalibrate thresholds from expert labels or historical outcomes:\n\n```bash\npython -m safeshift calibrate examples/example_adas_architecture.yaml \\\n  examples/example_expert_labels.csv \\\n  --out calibrated-risk-config.yaml\n```\n\nValidate ranking alignment:\n\n```bash\npython -m safeshift validate examples/example_adas_architecture.yaml \\\n  examples/example_expert_panel.csv \\\n  --format html \\\n  --out validation-dashboard.html\n```\n\n### 7. Generate reviewer-assist tasks\n\nReviewer-assist reports summarize review focus items and standards-evidence gaps while preserving\nprovenance, human-review requirements, and non-certification boundaries:\n\n```bash\npython -m safeshift ai-assist examples/example_adas_architecture.yaml \\\n  --review examples/example_review_state.csv \\\n  --standards-profile examples/standards_profile.yaml \\\n  --format html \\\n  --out ai-assist.html\n```\n\n### 8. Build one CI/review artifact bundle\n\nThe workflow runner can emit analysis reports, diffs, evidence packs, issue exports, validation\nartifacts, model cards, ingestion evidence, AI/ML reviewer-assist evidence, and readiness audits\ninto one directory.\n\n```bash\npython -m safeshift workflow examples/workflow.yaml --out-dir safeshift-artifacts\n```\n\nThen audit the bundle:\n\n```bash\npython -m safeshift workflow-audit safeshift-artifacts/manifest.json \\\n  --require-diff \\\n  --require-validation \\\n  --require-validation-audit \\\n  --require-model-card \\\n  --require-ai-assist \\\n  --required-ai-assist-formats json html \\\n  --require-ingestion-matrix \\\n  --required-ingestion-matrix-formats json html \\\n  --required-standards \"ISO 26262\" \"ISO/SAE 21434 / UNECE R155\" \\\n  --format html \\\n  --fail-on-audit \\\n  --out safeshift-artifacts/workflow-readiness-audit.html\n```\n\n## Inputs and Outputs\n\n### Supported inputs\n\n| Input type | Notes |\n| --- | --- |\n| SafeShift YAML/JSON | Native schema for components and directed interfaces. |\n| Component/interface CSV | Practical export path for architecture-management tools. |\n| AUTOSAR ARXML | Practical subset covering components, connectors, port interfaces, ECU mappings, communication clusters, and annotations. |\n| Generic REST sources | JSON, YAML, ARXML, or paired CSV endpoints. |\n| Mapped tool payloads | Bundled mapping profiles include `tool-json-basic`, `sysml-v2-json`, and `capella-semantic-json`. |\n\n### Supported outputs\n\n| Output | Best for |\n| --- | --- |\n| Markdown | Human-readable review notes. |\n| JSON | CI, dashboards, archival, and downstream tooling. |\n| CSV | Spreadsheet review and issue triage. |\n| HTML | Self-contained interactive dashboards. |\n| SARIF | Code-scanning and CI annotations. |\n| YAML | Normalized architecture and calibrated policy files. |\n\n## Example Architecture\n\nA minimal SafeShift architecture has components and directed interfaces:\n\n```yaml\nschema_version: \"1.0\"\nname: \"Minimal ADAS Architecture\"\n\ncomponents:\n  - id: camera\n    name: Front Camera\n    kind: sensor\n    supplier: SupplierA\n    asil: B\n    maturity: 0.8\n\n  - id: fusion\n    name: Fusion ECU\n    kind: software_module\n    supplier: SupplierB\n    asil: D\n    maturity: 0.4\n\ninterfaces:\n  - id: if_camera_fusion\n    source: camera\n    target: fusion\n    protocol: Ethernet\n    signals: 24\n    safety_related: true\n    timing_critical: true\n    cybersecurity_exposed: true\n```\n\nSee [`examples/example_adas_architecture.yaml`](examples/example_adas_architecture.yaml) and\n[`docs/schema.md`](docs/schema.md) for the full schema.\n\n## How Scoring Works\n\nSafeShift scores each interface using architecture and engineering signals such as:\n\n- supplier-boundary crossings;\n- safety and timing criticality;\n- ASIL and component maturity;\n- protocol complexity and signal count;\n- timing, bandwidth, and resource pressure;\n- cybersecurity exposure;\n- graph structure, including fan-in, fan-out, and dependency-cycle membership.\n\nThe default model is a transparent heuristic, so the tool works without training data. You can also\nrun an optional learned model:\n\n```bash\npython -m safeshift analyze examples/example_adas_architecture.yaml --train\n```\n\nRisk scores are decision-support indicators, not defect probabilities. Reports include reasons,\nscore contributors, confidence support, and evidence hooks so reviewers can understand why an\ninterface was prioritized.\n\n## CLI Command Map\n\n| Command | Purpose |\n| --- | --- |\n| `doctor` | Check local readiness for first-time use. |\n| `quickstart` | Run the bundled workflow and list generated reports. |\n| `wizard` | Prompt for common inputs and run a guided review. |\n| `open-report` | Open or print the primary HTML report for an artifact bundle. |\n| `ui` | Start the local browser UI. |\n| `analyze` | Score one architecture and render a report. |\n| `diff` | Compare two architecture versions. |\n| `import-csv` | Normalize component/interface CSV exports. |\n| `import-arxml` | Normalize AUTOSAR ARXML to SafeShift YAML/JSON. |\n| `architecture-fetch` | Fetch and normalize architecture data from a generic REST source. |\n| `arxml-audit` | Audit AUTOSAR import coverage and enrichment quality. |\n| `architecture-source-audit` | Audit fetched source evidence and normalization quality. |\n| `ingestion-matrix` | Prove multiple source variants normalize, audit, and analyze successfully. |\n| `review-template` | Generate a triage/review-state file. |\n| `evidence-template` | Generate a standards evidence checklist. |\n| `evidence-pack` | Aggregate standards evidence coverage and open gaps. |\n| `issue-export` | Export findings as portable issue records. |\n| `issue-import` | Merge tracker updates back into review state. |\n| `issue-push` | Dry-run or execute tracker API writes. |\n| `calibrate` | Calibrate LOW/MEDIUM/HIGH thresholds from labels or outcomes. |\n| `model-card` | Render a scoring-policy and decision-support card. |\n| `validate` | Validate rankings against one expert or historical-outcome study. |\n| `validate-cohort` | Validate across multiple studies. |\n| `validation-template` | Generate label-collection templates. |\n| `validation-protocol` | Generate an independent validation-study protocol. |\n| `validation-audit` | Audit validation evidence quality and leakage risks. |\n| `workflow` | Run a repeatable artifact bundle. |\n| `workflow-audit` | Check a workflow bundle for review readiness. |\n| `standards-profiles` | List bundled standards evidence profiles. |\n| `source-mapping-profiles` | List bundled architecture-source mapping profiles. |\n| `ai-assist` | Generate transparent reviewer-assist suggestions from findings. |\n\n## Repository Layout\n\n| Path | Purpose |\n| --- | --- |\n| [`src/safeshift`](src/safeshift) | Python package and CLI implementation. |\n| [`examples`](examples) | Example architectures, ARXML, CSV exports, workflows, validation inputs, and review state. |\n| [`docs`](docs) | Detailed usage and methodology documentation. |\n| [`evaluation`](evaluation) | Synthetic benchmark, robustness checks, scalability checks, and result artifacts. |\n| [`tests`](tests) | Unit tests for schema, graph, scoring, reports, workflow, and integrations. |\n\n## Documentation Map\n\n| Topic | Start here |\n| --- | --- |\n| Methodology and scoring rationale | [`docs/methodology.md`](docs/methodology.md) |\n| Native architecture schema | [`docs/schema.md`](docs/schema.md) |\n| CSV import | [`docs/csv-import.md`](docs/csv-import.md) |\n| AUTOSAR ARXML import | [`docs/autosar.md`](docs/autosar.md) |\n| Architecture-source integrations | [`docs/integrations.md`](docs/integrations.md) |\n| CI usage | [`docs/ci.md`](docs/ci.md) |\n| Guided CLI and local UI | [`docs/user-interface.md`](docs/user-interface.md) |\n| Review workflow | [`docs/review-workflow.md`](docs/review-workflow.md) |\n| Workflow bundles | [`docs/workflow.md`](docs/workflow.md) |\n| Score explanations | [`docs/explainability.md`](docs/explainability.md) |\n| Confidence support | [`docs/confidence.md`](docs/confidence.md) |\n| Calibration | [`docs/calibration.md`](docs/calibration.md) |\n| Validation | [`docs/validation.md`](docs/validation.md) |\n| Evidence packs | [`docs/evidence-pack.md`](docs/evidence-pack.md) |\n| Standards profiles | [`docs/standards-profile.md`](docs/standards-profile.md) |\n| Future plan and progress checks | [`docs/future-plan.md`](docs/future-plan.md) |\n\n## Worked Examples\n\nBundled examples include:\n\n- [`example_adas_architecture.yaml`](examples/example_adas_architecture.yaml): compact ADAS\n  reference architecture.\n- [`example_connected_vehicle_architecture.yaml`](examples/example_connected_vehicle_architecture.yaml):\n  connected-vehicle architecture covering telematics, V2X, OTA update, and infotainment.\n- [`example_autosar_annotations.arxml`](examples/example_autosar_annotations.arxml): AUTOSAR-style\n  export with safety, timing, supplier, and cybersecurity annotations.\n- [`example_components.csv`](examples/example_components.csv) and\n  [`example_interfaces.csv`](examples/example_interfaces.csv): CSV export example.\n- [`workflow.yaml`](examples/workflow.yaml): repeatable CI/review workflow bundle.\n- [`validation_cohort.yaml`](examples/validation_cohort.yaml): multi-study validation example.\n\n## Evaluation\n\nSafeShift includes a synthetic benchmark and evaluation harness:\n\n```bash\npip install -e \".[dev]\"\npython evaluation/run_eval.py\npython evaluation/extended.py all\n```\n\nThe included benchmark is useful for checking construct recovery, feature behavior, robustness, and\nruntime. It does not prove real-world predictive validity. Real deployment should calibrate and\nvalidate against an organization's historical integration outcomes or blinded expert review data.\n\nFull results are in [`evaluation/results.md`](evaluation/results.md), with additional robustness,\nsecurity, and scalability results in the same directory.\n\n## Scope and Limits\n\nSafeShift is a reference implementation and review method. It is not a certified tool, a compliance\nclaim, or a replacement for engineering judgment.\n\nImportant limits:\n\n- Risk scores are prioritization indicators, not guarantees that an interface will fail.\n- Learned mode uses synthetic training data unless you calibrate and validate it with your own data.\n- Standards hooks identify likely evidence needs; they do not establish ASPICE, ISO 26262,\n  ISO/SAE 21434, UNECE R155, or UNECE R156 compliance by themselves.\n- Importers preserve metadata where possible, but every source-tool export should be audited before\n  its scores are used in a formal review workflow.\n\n## Citation\n\nIf you use SafeShift, cite the archived software:\n\n\u003e Abdelmaksoud, O. SafeShift: Open Shift-Left Integration-Risk Prediction for Automotive Software\n\u003e Architectures. Zenodo. https://doi.org/10.5281/zenodo.20780068\n\nMachine-readable citation metadata is available in [`CITATION.cff`](CITATION.cff).\n\n## License\n\nApache-2.0. See [`LICENSE`](LICENSE).\n\n## Author\n\nCreated and maintained by Omar Abdelmaksoud.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foabdelmaksoud%2Fsafeshift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foabdelmaksoud%2Fsafeshift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foabdelmaksoud%2Fsafeshift/lists"}