How to Add a Live Security Badge to Your GitHub README

How to Add a Live Security Badge to Your GitHub README

Open source projects get judged fast. A contributor arriving at your repository has about 30 seconds before they decide whether to read further or close the tab. The README is your pitch: project description, installation instructions, license, and increasingly — a row of badges that signal quality at a glance.

Build status. Test coverage. License. Package version. And now, security score.

A live security badge tells contributors, security researchers, and potential users that your project has been scanned, that the score is real, and that it updates automatically. It is a statement of accountability.

What the Badge Shows

The ZeriFlow security badge displays your current /100 security score, color-coded by range:

• Green (90-100): Excellent security posture
• Yellow-green (80-89): Good — minor improvements available
• Yellow (70-79): Moderate — some issues to address
• Orange (60-69): Below average — notable gaps present
• Red (below 60): Poor — significant issues require attention

The score reflects the most recent ZeriFlow scan of your URL. Every time ZeriFlow scans your site (via scheduled monitoring, a CI/CD trigger, or a manual scan), the badge automatically reflects the new score. No manual update required.

The One-Line Implementation

Adding the badge to your README requires exactly one line of Markdown:

[![ZeriFlow Security Score](https://api.zeriflow.com/badge/YOUR_PROJECT_ID)](https://zeriflow.com/reports/YOUR_PROJECT_ID)

Replace YOUR_PROJECT_ID with the project ID from your ZeriFlow dashboard (found at Dashboard > Project > Settings > Badge). The badge is a standard SVG image served from the ZeriFlow CDN with cache headers set to refresh frequently so GitHub always serves the current score.

In practice, a full README badge row looks like this:

# My Project

[![Build Status](https://github.com/username/project/actions/workflows/ci.yml/badge.svg)](https://github.com/username/project/actions)
[![npm version](https://badge.fury.io/js/my-package.svg)](https://badge.fury.io/js/my-package)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123)](https://zeriflow.com/reports/proj_abc123)

That renders as a row of badges at the top of your README, with the security score badge linking directly to the public scan report.

HTML Embed for Websites and Docs

If you want to embed the badge on a project website, documentation site, or a landing page rather than a GitHub README, use the HTML version:

<!-- Standard embed -->
<a href="https://zeriflow.com/reports/proj_abc123">
  <img 
    src="https://api.zeriflow.com/badge/proj_abc123" 
    alt="ZeriFlow Security Score"
    height="20"
  />
</a>

<!-- With surrounding context -->
<div class="security-badge">
  <a href="https://zeriflow.com/reports/proj_abc123" target="_blank" rel="noopener noreferrer">
    <img 
      src="https://api.zeriflow.com/badge/proj_abc123" 
      alt="Security Score"
      height="20"
    />
  </a>
  <small>Continuously monitored by <a href="https://zeriflow.com">ZeriFlow</a></small>
</div>

For documentation sites built with tools like Docusaurus, VitePress, or MkDocs, the Markdown version works directly in most page templates. For Docusaurus specifically:

// docs/intro.mdx
import SecurityBadge from ''@site/src/components/SecurityBadge'';

# My API

[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123)](https://zeriflow.com/reports/proj_abc123)

Customizing Badge Appearance

ZeriFlow badges follow the standard Shields.io format and accept query parameters for customization:

<!-- Default style -->
[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123)](...)

<!-- Flat style -->
[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123?style=flat)](...)

<!-- Flat square -->
[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123?style=flat-square)](...)

<!-- For the badge -->
[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123?style=for-the-badge)](...)

<!-- Custom label text -->
[![Security](https://api.zeriflow.com/badge/proj_abc123?label=security)](...)

<!-- Custom logo -->
[![ZeriFlow Security Score](https://api.zeriflow.com/badge/proj_abc123?logo=shield&logoColor=white)](...)

The for-the-badge style is particularly readable in READMEs that use larger badges throughout, as it matches the aesthetic of GitHub Action status badges and is more legible at a glance.

How Frequently the Badge Updates

The badge SVG is served with a Cache-Control: max-age=300, s-maxage=300 header, meaning it can be cached for up to 5 minutes. In practice:

• GitHub''s Camo image proxy caches badge images for a few minutes, so there is a small delay between a score change and the badge reflecting it
• Your browser may cache the badge longer — force-refresh with Ctrl+Shift+R to see the current value
• ZeriFlow scans update the underlying score immediately — the badge reflects the most recent scan result

For projects where the score matters for compliance or public visibility, you can trigger a fresh scan via the API after every deployment to ensure the badge reflects the current production state:

# In your deployment pipeline, after the deployment completes:
curl -X POST https://api.zeriflow.com/scan-quick \\
  -H "X-API-Key: $ZERIFLOW_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d ''{"url": "https://your-app.com"}''

# The badge will reflect the new score within minutes

Why the Badge Builds Real Trust

A hardcoded "We take security seriously" claim in a README is marketing copy. A live security score badge backed by an automated scan is a verifiable claim.

Here is what the badge communicates to different audiences:

Open source contributors see that the project is actively maintained with security in mind. A score of 85+ suggests that security headers are configured, TLS is set up correctly, and the maintainer cares about the project''s security posture. This is a meaningful signal when deciding whether to use a library in production.

Enterprise evaluators conducting due diligence on third-party dependencies use security scores as a quick filter. A project with a visible, current security score is significantly easier to approve in a security review than one with no security documentation.

Security researchers looking for vulnerability disclosure candidates often look for projects that show security awareness. A project with a public security score sends a signal that it''s actively monitored — researchers know that any finding they report will likely be taken seriously.

The project maintainer benefits from the accountability structure. A public badge creates a social contract: if the score drops, it''s visible to everyone. This creates a natural incentive to keep the score high, which means keeping the security configuration maintained.

Setting Up the Badge: Step-by-Step

1. 1Create a ZeriFlow account at zeriflow.com — free, no credit card required

1. 1Run your first scan: Enter your URL in the dashboard or use the free scan at the homepage. ZeriFlow will run 80+ checks and produce a score in under 60 seconds.

1. 1Find your badge code: Navigate to Dashboard > Your Project > Settings > Badge. The Markdown and HTML embed codes are pre-generated.

1. 1Add to your README: Paste the one-line Markdown at the top of your README file, next to your other quality badges.

1. 1Verify it appears: Push the change to GitHub and view your repository page. The badge should appear immediately with your current score.

Keeping the Score High After the Badge Is Public

Publishing a security score badge is a commitment. Here is a minimal ongoing process to keep it green:

• Enable ZeriFlow monitoring (daily scans, Slack alerts) so you know immediately when the score drops
• Add the ZeriFlow CI check to your GitHub Actions workflow so deployments that degrade the score are blocked before they reach production
• Review the full report monthly and work through the medium-severity findings

Most projects with a score above 80 got there by fixing a handful of high-impact issues: enabling HSTS, adding a Content-Security-Policy, configuring the correct CORS settings, and ensuring no sensitive files are publicly accessible. These fixes are usually straightforward once you know what to look for.

Conclusion

One line of Markdown. That is the entire implementation. The badge pulls its value from the live ZeriFlow scan, updates automatically, and links to the full public report. It is the lowest-effort way to make your project''s security posture visible and verifiable.

Add it today — scan your project at zeriflow.com, find your badge code in the dashboard, and paste it into your README. The free tier covers this entirely.