https://github.com/oabdelmaksoud/safeshift

Open, vendor-neutral shift-left integration-risk prediction for automotive software architectures
https://github.com/oabdelmaksoud/safeshift
aspice automotive iso-26262 machine-learning safety-critical shift-left software-defined-vehicle
Last synced: 3 days ago
JSON representation
Open, vendor-neutral shift-left integration-risk prediction for automotive software architectures
Host: GitHub
URL: https://github.com/oabdelmaksoud/safeshift
Owner: oabdelmaksoud
License: apache-2.0
Created: 2026-06-20T19:10:21.000Z (6 days ago)
Default Branch: main
Last Pushed: 2026-06-21T03:18:51.000Z (6 days ago)
Last Synced: 2026-06-21T05:10:28.978Z (5 days ago)
Topics: aspice, automotive, iso-26262, machine-learning, safety-critical, shift-left, software-defined-vehicle
Language: Python
Size: 368 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project

README

          # SafeShift

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20780068.svg)](https://doi.org/10.5281/zenodo.20780068)

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)

SafeShift is an open, vendor-neutral toolkit for finding likely integration-risk hotspots in

automotive software and E/E architectures before late-stage integration.

It helps architecture, safety, cybersecurity, and CI teams answer:

> Which interfaces deserve review first, and what evidence should reviewers collect?

SafeShift reads architecture data, builds a dependency graph, scores each interface, and emits

review-ready reports, dashboards, SARIF, evidence packs, issue records, and CI workflow artifacts.

```mermaid

flowchart LR

    A["Architecture sources"] --> B["SafeShift schema"]

    B --> C["Dependency graph and features"]

    C --> D["Risk scoring and confidence"]

    D --> E["Reports, dashboards, SARIF, evidence packs, CI gates"]

```

## Contents

- [Why SafeShift Exists](#why-safeshift-exists)

- [What It Can Do](#what-it-can-do)

- [Install](#install)

- [First Run](#first-run)

- [Quickstart](#quickstart)

- [Common Workflows](#common-workflows)

- [Inputs and Outputs](#inputs-and-outputs)

- [Example Architecture](#example-architecture)

- [How Scoring Works](#how-scoring-works)

- [CLI Command Map](#cli-command-map)

- [Repository Layout](#repository-layout)

- [Documentation Map](#documentation-map)

- [Worked Examples](#worked-examples)

- [Evaluation](#evaluation)

- [Scope and Limits](#scope-and-limits)

- [Citation](#citation)

- [License](#license)

## Why SafeShift Exists

Modern vehicles integrate many electronic control units, software modules, suppliers, and tool

chains. Architecture and integration defects found after physical builds are expensive, slow, and

often connected to safety, timing, cybersecurity, or supplier-boundary complexity.

SafeShift moves part of that review earlier. It is designed to be:

- **Open**: no proprietary data model or hosted service is required.

- **Auditable**: reports include feature-level reasons and evidence hooks.

- **CI-friendly**: outputs include JSON, CSV, HTML, Markdown, and SARIF.

- **Workflow-oriented**: review state, evidence packs, validation reports, and bundle audits are

  first-class artifacts.

## What It Can Do

| Capability | What you get |

| --- | --- |

| Architecture risk analysis | Ranked LOW/MEDIUM/HIGH integration-risk findings per interface. |

| Architecture diffing | Added, removed, and changed interfaces with material risk deltas. |

| Source normalization | YAML/JSON, CSV, mapped tool payloads, generic REST sources, and AUTOSAR ARXML. |

| Import-quality audits | ARXML, architecture-source, and ingestion-matrix evidence before trusting scores. |

| Review tracking | Owner, status, decision, mitigation, due date, notes, and evidence references. |

| AI/ML reviewer assistance | Traceable review-focus and evidence-gap suggestions with provenance, human-review controls, and no default external AI calls. |

| Standards evidence | Evidence hooks and evidence packs for ASPICE, ISO 26262, ISO/SAE 21434, UNECE R155, and UNECE R156. |

| Issue handoff | Portable issue records for GitHub, Jira-style APIs, generic HTTP endpoints, or manual boards. |

| Calibration and validation | Threshold calibration, expert-panel validation, historical-outcome validation, and cohort reports. |

| CI artifact bundles | Repeatable workflow runs with manifests, dashboards, gates, and readiness audits. |

| Guided operation | `doctor`, `quickstart`, `wizard`, `open-report`, and a local browser UI for users who do not want to memorize long commands. |

## Install

SafeShift requires Python 3.9 or newer.

From the repository root:

```bash

pip install -e .

```

Optional installs:

```bash

pip install -e ".[ml]"   # enables the optional RandomForest model

pip install -e ".[dev]"  # installs test and evaluation dependencies

```

After installation, either command style works:

```bash

python -m safeshift --help

safeshift --help

```

## First Run

Use the guided path when you want SafeShift to behave like an interface rather than an expert-only

CLI.

Check the local setup:

```bash

python -m safeshift doctor

```

Run the bundled review workflow and list generated reports:

```bash

python -m safeshift quickstart --out-dir safeshift-demo

```

Open the primary HTML report from that bundle:

```bash

python -m safeshift open-report safeshift-demo

```

Start the local browser UI:

```bash

python -m safeshift ui

```

The browser UI lets a user upload or select an architecture file, choose guided review or an

existing workflow, run SafeShift, then open or download risk, AI-assist, evidence-gap, model-card,

and readiness reports. Use `python -m safeshift wizard` for a prompt-driven terminal flow.

## Quickstart

Generate a self-contained HTML dashboard from the bundled ADAS example:

```bash

python -m safeshift analyze examples/example_adas_architecture.yaml \

  --format html \

  --out safeshift-dashboard.html

```

Print a Markdown report in the terminal:

```bash

python -m safeshift analyze examples/example_adas_architecture.yaml

```

Compare two architecture versions:

```bash

python -m safeshift diff \

  examples/example_adas_architecture.yaml \

  examples/example_adas_architecture_update.yaml \

  --format html \

  --out safeshift-diff.html

```

Run the full example review workflow:

```bash

python -m safeshift workflow examples/workflow.yaml --out-dir safeshift-artifacts

```

Run tests:

```bash

pip install -e ".[dev]"

pytest

```

## Common Workflows

### 1. Analyze an architecture

Use this for the main risk report.

```bash

python -m safeshift analyze examples/example_adas_architecture.yaml \

  --format markdown \

  --out report.md

```

Useful formats:

- `markdown`: human-readable report.

- `json`: machine-readable artifact for dashboards and CI.

- `csv`: spreadsheet-friendly finding export.

- `html`: self-contained review dashboard.

- `sarif`: code-scanning and CI integrations.

### 2. Add review state

Create a review template, fill it in, then include it in later reports.

```bash

python -m safeshift review-template examples/example_adas_architecture.yaml \

  --out review.csv

python -m safeshift analyze examples/example_adas_architecture.yaml \

  --review review.csv \

  --format html \

  --out reviewed-dashboard.html

```

### 3. Create standards evidence

Generate a checklist or an aggregated evidence pack for architecture review.

```bash

python -m safeshift evidence-template examples/example_adas_architecture.yaml \

  --out evidence-checklist.csv

python -m safeshift evidence-pack examples/example_adas_architecture.yaml \

  --review examples/example_review_state.csv \

  --min-band HIGH \

  --format html \

  --out evidence-pack.html

```

### 4. Import architecture data from other tools

Convert CSV exports:

```bash

python -m safeshift import-csv \

  --components examples/example_components.csv \

  --interfaces examples/example_interfaces.csv \

  --name "CSV ADAS Export" \

  --out csv-architecture.yaml

```

Analyze AUTOSAR ARXML directly or convert it first:

```bash

python -m safeshift analyze examples/example_autosar_annotations.arxml

python -m safeshift import-arxml examples/example_autosar_subset.arxml \

  --out arxml-architecture.yaml

```

Audit an ARXML import before relying on it:

```bash

python -m safeshift arxml-audit examples/example_autosar_annotations.arxml \

  --format html \

  --fail-on-audit \

  --out arxml-import-audit.html

```

### 5. Export issues for review handoff

```bash

python -m safeshift issue-export examples/example_adas_architecture.yaml \

  --review examples/example_review_state.csv \

  --min-band HIGH \

  --format json \

  --out safeshift-issues.json

```

Dry-run an issue push plan:

```bash

python -m safeshift issue-push safeshift-issues.json \

  --provider github \

  --target owner/repo \

  --out issue-push-plan.json

```

### 6. Calibrate and validate

Calibrate thresholds from expert labels or historical outcomes:

```bash

python -m safeshift calibrate examples/example_adas_architecture.yaml \

  examples/example_expert_labels.csv \

  --out calibrated-risk-config.yaml

```

Validate ranking alignment:

```bash

python -m safeshift validate examples/example_adas_architecture.yaml \

  examples/example_expert_panel.csv \

  --format html \

  --out validation-dashboard.html

```

### 7. Generate reviewer-assist tasks

Reviewer-assist reports summarize review focus items and standards-evidence gaps while preserving

provenance, human-review requirements, and non-certification boundaries:

```bash

python -m safeshift ai-assist examples/example_adas_architecture.yaml \

  --review examples/example_review_state.csv \

  --standards-profile examples/standards_profile.yaml \

  --format html \

  --out ai-assist.html

```

### 8. Build one CI/review artifact bundle

The workflow runner can emit analysis reports, diffs, evidence packs, issue exports, validation

artifacts, model cards, ingestion evidence, AI/ML reviewer-assist evidence, and readiness audits

into one directory.

```bash

python -m safeshift workflow examples/workflow.yaml --out-dir safeshift-artifacts

```

Then audit the bundle:

```bash

python -m safeshift workflow-audit safeshift-artifacts/manifest.json \

  --require-diff \

  --require-validation \

  --require-validation-audit \

  --require-model-card \

  --require-ai-assist \

  --required-ai-assist-formats json html \

  --require-ingestion-matrix \

  --required-ingestion-matrix-formats json html \

  --required-standards "ISO 26262" "ISO/SAE 21434 / UNECE R155" \

  --format html \

  --fail-on-audit \

  --out safeshift-artifacts/workflow-readiness-audit.html

```

## Inputs and Outputs

### Supported inputs

| Input type | Notes |

| --- | --- |

| SafeShift YAML/JSON | Native schema for components and directed interfaces. |

| Component/interface CSV | Practical export path for architecture-management tools. |

| AUTOSAR ARXML | Practical subset covering components, connectors, port interfaces, ECU mappings, communication clusters, and annotations. |

| Generic REST sources | JSON, YAML, ARXML, or paired CSV endpoints. |

| Mapped tool payloads | Bundled mapping profiles include `tool-json-basic`, `sysml-v2-json`, and `capella-semantic-json`. |

### Supported outputs

| Output | Best for |

| --- | --- |

| Markdown | Human-readable review notes. |

| JSON | CI, dashboards, archival, and downstream tooling. |

| CSV | Spreadsheet review and issue triage. |

| HTML | Self-contained interactive dashboards. |

| SARIF | Code-scanning and CI annotations. |

| YAML | Normalized architecture and calibrated policy files. |

## Example Architecture

A minimal SafeShift architecture has components and directed interfaces:

```yaml

schema_version: "1.0"

name: "Minimal ADAS Architecture"

components:

  - id: camera

    name: Front Camera

    kind: sensor

    supplier: SupplierA

    asil: B

    maturity: 0.8

  - id: fusion

    name: Fusion ECU

    kind: software_module

    supplier: SupplierB

    asil: D

    maturity: 0.4

interfaces:

  - id: if_camera_fusion

    source: camera

    target: fusion

    protocol: Ethernet

    signals: 24

    safety_related: true

    timing_critical: true

    cybersecurity_exposed: true

```

See [`examples/example_adas_architecture.yaml`](examples/example_adas_architecture.yaml) and

[`docs/schema.md`](docs/schema.md) for the full schema.

## How Scoring Works

SafeShift scores each interface using architecture and engineering signals such as:

- supplier-boundary crossings;

- safety and timing criticality;

- ASIL and component maturity;

- protocol complexity and signal count;

- timing, bandwidth, and resource pressure;

- cybersecurity exposure;

- graph structure, including fan-in, fan-out, and dependency-cycle membership.

The default model is a transparent heuristic, so the tool works without training data. You can also

run an optional learned model:

```bash

python -m safeshift analyze examples/example_adas_architecture.yaml --train

```

Risk scores are decision-support indicators, not defect probabilities. Reports include reasons,

score contributors, confidence support, and evidence hooks so reviewers can understand why an

interface was prioritized.

## CLI Command Map

| Command | Purpose |

| --- | --- |

| `doctor` | Check local readiness for first-time use. |

| `quickstart` | Run the bundled workflow and list generated reports. |

| `wizard` | Prompt for common inputs and run a guided review. |

| `open-report` | Open or print the primary HTML report for an artifact bundle. |

| `ui` | Start the local browser UI. |

| `analyze` | Score one architecture and render a report. |

| `diff` | Compare two architecture versions. |

| `import-csv` | Normalize component/interface CSV exports. |

| `import-arxml` | Normalize AUTOSAR ARXML to SafeShift YAML/JSON. |

| `architecture-fetch` | Fetch and normalize architecture data from a generic REST source. |

| `arxml-audit` | Audit AUTOSAR import coverage and enrichment quality. |

| `architecture-source-audit` | Audit fetched source evidence and normalization quality. |

| `ingestion-matrix` | Prove multiple source variants normalize, audit, and analyze successfully. |

| `review-template` | Generate a triage/review-state file. |

| `evidence-template` | Generate a standards evidence checklist. |

| `evidence-pack` | Aggregate standards evidence coverage and open gaps. |

| `issue-export` | Export findings as portable issue records. |

| `issue-import` | Merge tracker updates back into review state. |

| `issue-push` | Dry-run or execute tracker API writes. |

| `calibrate` | Calibrate LOW/MEDIUM/HIGH thresholds from labels or outcomes. |

| `model-card` | Render a scoring-policy and decision-support card. |

| `validate` | Validate rankings against one expert or historical-outcome study. |

| `validate-cohort` | Validate across multiple studies. |

| `validation-template` | Generate label-collection templates. |

| `validation-protocol` | Generate an independent validation-study protocol. |

| `validation-audit` | Audit validation evidence quality and leakage risks. |

| `workflow` | Run a repeatable artifact bundle. |

| `workflow-audit` | Check a workflow bundle for review readiness. |

| `standards-profiles` | List bundled standards evidence profiles. |

| `source-mapping-profiles` | List bundled architecture-source mapping profiles. |

| `ai-assist` | Generate transparent reviewer-assist suggestions from findings. |

## Repository Layout

| Path | Purpose |

| --- | --- |

| [`src/safeshift`](src/safeshift) | Python package and CLI implementation. |

| [`examples`](examples) | Example architectures, ARXML, CSV exports, workflows, validation inputs, and review state. |

| [`docs`](docs) | Detailed usage and methodology documentation. |

| [`evaluation`](evaluation) | Synthetic benchmark, robustness checks, scalability checks, and result artifacts. |

| [`tests`](tests) | Unit tests for schema, graph, scoring, reports, workflow, and integrations. |

## Documentation Map

| Topic | Start here |

| --- | --- |

| Methodology and scoring rationale | [`docs/methodology.md`](docs/methodology.md) |

| Native architecture schema | [`docs/schema.md`](docs/schema.md) |

| CSV import | [`docs/csv-import.md`](docs/csv-import.md) |

| AUTOSAR ARXML import | [`docs/autosar.md`](docs/autosar.md) |

| Architecture-source integrations | [`docs/integrations.md`](docs/integrations.md) |

| CI usage | [`docs/ci.md`](docs/ci.md) |

| Guided CLI and local UI | [`docs/user-interface.md`](docs/user-interface.md) |

| Review workflow | [`docs/review-workflow.md`](docs/review-workflow.md) |

| Workflow bundles | [`docs/workflow.md`](docs/workflow.md) |

| Score explanations | [`docs/explainability.md`](docs/explainability.md) |

| Confidence support | [`docs/confidence.md`](docs/confidence.md) |

| Calibration | [`docs/calibration.md`](docs/calibration.md) |

| Validation | [`docs/validation.md`](docs/validation.md) |

| Evidence packs | [`docs/evidence-pack.md`](docs/evidence-pack.md) |

| Standards profiles | [`docs/standards-profile.md`](docs/standards-profile.md) |

| Future plan and progress checks | [`docs/future-plan.md`](docs/future-plan.md) |

## Worked Examples

Bundled examples include:

- [`example_adas_architecture.yaml`](examples/example_adas_architecture.yaml): compact ADAS

  reference architecture.

- [`example_connected_vehicle_architecture.yaml`](examples/example_connected_vehicle_architecture.yaml):

  connected-vehicle architecture covering telematics, V2X, OTA update, and infotainment.

- [`example_autosar_annotations.arxml`](examples/example_autosar_annotations.arxml): AUTOSAR-style

  export with safety, timing, supplier, and cybersecurity annotations.

- [`example_components.csv`](examples/example_components.csv) and

  [`example_interfaces.csv`](examples/example_interfaces.csv): CSV export example.

- [`workflow.yaml`](examples/workflow.yaml): repeatable CI/review workflow bundle.

- [`validation_cohort.yaml`](examples/validation_cohort.yaml): multi-study validation example.

## Evaluation

SafeShift includes a synthetic benchmark and evaluation harness:

```bash

pip install -e ".[dev]"

python evaluation/run_eval.py

python evaluation/extended.py all

```

The included benchmark is useful for checking construct recovery, feature behavior, robustness, and

runtime. It does not prove real-world predictive validity. Real deployment should calibrate and

validate against an organization's historical integration outcomes or blinded expert review data.

Full results are in [`evaluation/results.md`](evaluation/results.md), with additional robustness,

security, and scalability results in the same directory.

## Scope and Limits

SafeShift is a reference implementation and review method. It is not a certified tool, a compliance

claim, or a replacement for engineering judgment.

Important limits:

- Risk scores are prioritization indicators, not guarantees that an interface will fail.

- Learned mode uses synthetic training data unless you calibrate and validate it with your own data.

- Standards hooks identify likely evidence needs; they do not establish ASPICE, ISO 26262,

  ISO/SAE 21434, UNECE R155, or UNECE R156 compliance by themselves.

- Importers preserve metadata where possible, but every source-tool export should be audited before

  its scores are used in a formal review workflow.

## Citation

If you use SafeShift, cite the archived software:

> Abdelmaksoud, O. SafeShift: Open Shift-Left Integration-Risk Prediction for Automotive Software

> Architectures. Zenodo. https://doi.org/10.5281/zenodo.20780068

Machine-readable citation metadata is available in [`CITATION.cff`](CITATION.cff).

## License

Apache-2.0. See [`LICENSE`](LICENSE).

## Author

Created and maintained by Omar Abdelmaksoud.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/oabdelmaksoud/safeshift

Awesome Lists containing this project

README
