Getting started with Firmlint

Everything you need to run your first analysis. 10 minutes start to finish.

Requirements

• Docker installed and running (Desktop or Engine, any recent version)
• ~2 GB free disk space for the image and cache
• Your C or C++ source code on the local filesystem
• (Optional) Ollama installed if you want the AI explanations to run locally

1 · Install the Docker image

Pull the image from GitHub Container Registry:

$ docker pull ghcr.io/ibrarmohammed1137/misra-assistant:latest

The image is public — no login required. Expect ~500 MB download.

2 · Run your first analysis

From your project directory, mount the current folder and pass a file to analyze:

$ docker run --rm -v "$(pwd):/app" -w /app \
    ghcr.io/ibrarmohammed1137/misra-assistant:latest \
    python -m agent.run samples/demo.cpp --standard autosar-cpp14

What the flags mean:

• -v "$(pwd):/app" — mount your current directory into the container as /app
• -w /app — set the working directory inside the container
• --standard autosar-cpp14 — pick a rule set (see §4)

After the run, look in ./out/. You'll find:

• report.html — human-readable report
• report.json — machine-readable, includes SHA-256 of every file
• report.sarif — for IDE and CI integration

3 · Reading the report

Open out/report.html in any browser. You'll see:

• Summary — count of findings by priority (critical / high / medium / low)
• Reviewed findings — findings the AI has explained, each with:
  • Rule ID (e.g. AUTOSAR A18-5-1)
  • Location (file and line)
  • Analyzer source (cppcheck or clang-tidy)
  • Plain-English explanation
  • Risk statement
• Other findings — violations found but outside the AI review limit
• Scope and evidence — tool versions, timestamps, SHA-256 of analyzed files
• Limitations — honest disclosure of what the report does and doesn't tell you

4 · Choosing a standard

Pass --standard to pick a rule set:

--standard misra-c-2012       MISRA C:2012
--standard misra-cpp-2023     MISRA C++:2023
--standard autosar-cpp14      AUTOSAR C++14
--standard cert-c             CERT C
--standard cwe-top-25         CWE Top 25

Run without --standard to use the default (MISRA C:2012 for .c files, AUTOSAR C++14 for .cpp files).

5 · Enabling local AI (optional)

The deterministic layer (cppcheck, clang-tidy) works without any AI. To enable the AI explanations with local inference:

1. Install Ollama on your host machine
2. Pull a model: ollama pull qwen2.5-coder:14b
3. Run the container with Ollama access:

   $ docker run --rm -v "$(pwd):/app" -w /app \
       --add-host=host.docker.internal:host-gateway \
       -e OLLAMA_HOST=http://host.docker.internal:11434 \
       ghcr.io/ibrarmohammed1137/misra-assistant:latest \
       python -m agent.run samples/demo.cpp --standard autosar-cpp14

Your code still never leaves your machine — only local inference is used.

6 · CI/CD integration

Add this step to your pipeline (GitHub Actions example):

- name: Firmlint
  run: |
    docker pull ghcr.io/ibrarmohammed1137/misra-assistant:latest
    docker run --rm -v "$PWD:/app" -w /app \
      ghcr.io/ibrarmohammed1137/misra-assistant:latest \
      python -m agent.run src/ --standard misra-c-2012

- name: Upload report
  uses: actions/upload-artifact@v4
  with:
    name: firmlint-report
    path: out/

The SARIF output (out/report.sarif) can be uploaded to GitHub's code-scanning tab directly.

Troubleshooting

Docker says "denied: denied"

Your Docker daemon isn't authenticated to GHCR. Log out and pull again:

$ docker logout ghcr.io
$ docker pull ghcr.io/ibrarmohammed1137/misra-assistant:latest

Report has 0 findings but code should have violations

Check the "Coverage" section in the report. It lists which rules fired. If your rule isn't in the rule database, it isn't checked. Partial coverage is expected — see the Limitations section.

AI explanations are missing

The AI layer is optional. If Ollama isn't running or reachable, findings will show the analyzer message but no explanation. See §5 to enable it.

Container can't see my files

Check the volume mount. On Windows, use $(pwd) in Git Bash or ${PWD} in PowerShell. The path must be absolute.

Still stuck?

Email hello@firmlint.com with:

• The exact command you ran
• The full output (copy-paste, not a screenshot)
• Your OS and Docker version

We answer within one business day.