javierattorq/qr-decoder repository overview

⁠QR Code Decoder - Custom Step for Torq

A production-ready Docker container that decodes QR codes from URLs with automatic fallback strategies for maximum reliability.

⁠🚀 Quick Start

docker run --rm \
  -e URL_TO_IMAGE=https://example.com/qrcode.png \
  javierattorq/qr-decoder:latest

Output:

{
  "output": {
    "qr_detected": true,
    "qr_strings": "https://decoded-content.com",
    "version": "1.3.3",
    "library": "pyzbar"
  }
}

⁠✨ Features

• 🎯 Automatic Decoder Selection - Tries pyzbar first (most reliable), falls back to OpenCV
• 🔄 7 Preprocessing Strategies - Maximum compatibility with various QR code formats
• 📦 Clean JSON Output - Structured, parseable output for easy integration
• 🌐 Multi-Architecture - Supports both AMD64 and ARM64
• ⚡ Torq Platform Ready - Optimized for Torq security workflows
• 🔒 Malware Analysis - Perfect for analyzing suspicious QR codes

⁠📋 Output Format

All responses return structured JSON:

{
  "output": {
    "qr_detected": boolean,    // true if QR code was found
    "qr_strings": string,       // decoded content
    "version": string,          // container version
    "library": string           // decoder used (pyzbar/opencv/none)
  }
}

⁠🎯 Use Cases

⁠Cybersecurity

• Phishing Detection - Decode QR codes from suspicious emails
• Malware Analysis - Extract URLs from QR-based malware
• Incident Response - Quick analysis during security investigations

⁠Automation

• Batch Processing - Process multiple QR codes in workflows
• URL Extraction - Automated URL harvesting from images
• Content Verification - Validate QR code contents

⁠Integration

• Torq Workflows - Native integration with Torq platform
• Security Pipelines - Add to your security automation
• SOAR Platforms - Integrate with security orchestration tools

⁠💻 Usage Examples

⁠Basic Decode

docker run --rm \
  -e URL_TO_IMAGE=https://suspicious-email.com/qr.png \
  javierattorq/qr-decoder:latest

⁠With Result Parsing (Bash)

result=$(docker run --rm \
  -e URL_TO_IMAGE="$image_url" \
  javierattorq/qr-decoder:latest)

if echo "$result" | jq -e '.output.qr_detected' > /dev/null; then
    decoded_url=$(echo "$result" | jq -r '.output.qr_strings')
    echo "Decoded URL: $decoded_url"
fi

⁠With Result Parsing (Python)

import subprocess
import json

result = subprocess.run(
    ["docker", "run", "--rm",
     "-e", f"URL_TO_IMAGE={image_url}",
     "javierattorq/qr-decoder:latest"],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
if data['output']['qr_detected']:
    print(f"Decoded: {data['output']['qr_strings']}")
    print(f"Library: {data['output']['library']}")

⁠Error Handling

# No URL provided
$ docker run --rm javierattorq/qr-decoder:latest
{
  "output": {
    "qr_detected": false,
    "qr_strings": "URL_TO_IMAGE environment variable not set",
    "version": "1.3.3",
    "library": "none"
  }
}

# No QR code found
$ docker run --rm -e URL_TO_IMAGE=https://example.com/plain-image.jpg javierattorq/qr-decoder:latest
{
  "output": {
    "qr_detected": false,
    "qr_strings": "No QR code found",
    "version": "1.3.3",
    "library": "none"
  }
}

⁠🔧 Environment Variables

⁠🏗️ How It Works

1. Download - Fetches image from provided URL
2. Try pyzbar - Attempts decode with zbar library (95% success rate)
3. Fallback to OpenCV - If pyzbar fails, tries 7 preprocessing methods:
   • Original image
   • Grayscale conversion
   • Enhanced contrast
   • Gaussian blur
   • Adaptive threshold
   • Binary threshold
   • Otsu threshold
4. Return JSON - Structured output with decoded content

⁠📊 Decoder Comparison

⁠🐳 Available Tags

Recommended: Always use latest or a specific version tag for production.

⁠🔒 Security Features

• ✅ Sandboxed Execution - Runs in isolated container
• ✅ No Persistent Storage - Downloads are temporary and cleaned up
• ✅ Minimal Attack Surface - Slim base image
• ✅ Read-Only Operation - No modification of downloaded files
• ✅ Safe URL Processing - Handles malicious URLs safely

⁠⚙️ Technical Details

⁠Base Image

• python:3.11-slim (Debian Bookworm)

⁠Installed Libraries

• pyzbar - Primary QR decoder
• zbar-tools - System zbar library
• opencv-python-headless - Fallback decoder
• pillow - Image processing
• requests - HTTP client

⁠Architecture Support

• ✅ linux/amd64 (x86_64)
• ✅ linux/arm64 (ARM64/Apple Silicon)

⁠Container Size

• Compressed: ~180MB
• Uncompressed: ~500MB

⁠🚦 Integration Examples

⁠Torq Workflow

steps:
  - name: Decode QR Code
    image: javierattorq/qr-decoder:latest
    environment:
      URL_TO_IMAGE: "{{ incident.qr_code_url }}"

  - name: Process URL
    condition: "{{ steps.decode_qr.output.qr_detected }}"
    script: |
      url="${{ steps.decode_qr.output.qr_strings }}"
      # Analyze decoded URL...

⁠Docker Compose

version: '3.8'
services:
  qr-decoder:
    image: javierattorq/qr-decoder:latest
    environment:
      - URL_TO_IMAGE=${QR_IMAGE_URL}

⁠Kubernetes Job

apiVersion: batch/v1
kind: Job
metadata:
  name: qr-decode-job
spec:
  template:
    spec:
      containers:
      - name: qr-decoder
        image: javierattorq/qr-decoder:latest
        env:
        - name: URL_TO_IMAGE
          value: "https://example.com/qr.png"
      restartPolicy: Never

⁠📈 Performance

• Average Decode Time: 2-5 seconds (including download)
• Success Rate: 95% with pyzbar, 60% with OpenCV
• Memory Usage: ~100-200MB per container
• CPU Usage: Low (single-threaded)

⁠🆘 Troubleshooting

⁠Container exits immediately

Solution: Ensure URL_TO_IMAGE environment variable is set.

⁠"Failed to download image"

Causes:

• URL is not accessible
• Network connectivity issues
• Invalid image format

Solution: Verify URL is publicly accessible and points to a valid image (PNG, JPG, etc.)

⁠"No QR code found"

Causes:

• Image quality too low
• QR code too small or distorted
• Not a QR code

Solution: Ensure image contains a clear, readable QR code.

⁠"exec format error"

Cause: Architecture mismatch

Solution: Specify platform explicitly:

docker run --platform linux/amd64 --rm -e URL_TO_IMAGE=<url> javierattorq/qr-decoder:latest

⁠📚 Documentation

• GitHub Repository: https://github.com/javier-at-torq/QRDecoder-Custom-Step⁠
• Contributing Guide: CONTRIBUTING.md⁠
• License: MIT License⁠

⁠🤝 Contributing

Contributions welcome! Please see our Contributing Guide⁠.

⁠📧 Support

• Issues: GitHub Issues⁠
• Email: [email protected]⁠
• Documentation: GitHub Wiki⁠

⁠📄 License

MIT License - see LICENSE⁠ for details.

⁠🔗 Links

• Docker Hub: https://hub.docker.com/r/javierattorq/qr-decoder⁠
• Source Code: https://github.com/javier-at-torq/QRDecoder-Custom-Step⁠
• Torq Platform: https://torq.io⁠

Built for Security Teams | Powered by Torq

Last Updated: February 2026 | Version: 1.3.3