active_storage_av_scan 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6df5649080705ad47fb181490a51ab55ee685b4dc935cb8bf4a6847da82a641
+  data.tar.gz: 51026120b1bc776676b671af11086bd06720b2715a2437109d575c07259f71bf
+SHA512:
+  metadata.gz: e09e7d0ece60314e0bb25dee6175de5c05f98f224bb549a1f17db84aab147750a72732bad24d413201c42a83c3f9cc2c858514fb248e6e51b6a662a66391b397
+  data.tar.gz: f46df87bf21899c76aee4f8668158aa96274843012f40a33b7945bc590cb471ad38adc567f18f657ef983210423ae50d870acdd74d136264897ee4e55f9976e4

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-07
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,285 @@
+
+# ActiveStorage AV Scan
+
+A lightweight antivirus scanning extension for **Rails Active Storage**.
+Automatically scans uploaded files using **ClamAV**, records results, and exposes clean helpers for models and views.
+
+> ⚠️ Currently an **early release (`v0.1.0`)** — battle-tested in real Rails apps, but specs and HTTP/Lambda integrations are coming soon.
+
+---
+
+## Features
+
+- Automatic background scanning of Active Storage attachments
+- Adapter-agnostic — works with **Sidekiq**, **SolidQueue**, **Resque**, or any ActiveJob backend
+- Built-in **ClamAV scanner**
+- Dedicated `AttachmentScan` model to store results
+- Easy **view helpers** for showing scan status
+- Configurable **infection policy** (`infected_handler`)
+
+---
+
+## 🚀 Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "active_storage_av_scan"
+````
+
+Install and migrate:
+
+```bash
+bundle install
+bundle exec rails g active_storage_av_scan:install
+bundle exec rails db:migrate
+```
+
+This creates:
+
+* The `active_storage_attachment_scans` table
+* An initializer at `config/initializers/active_storage_av_scan.rb`
+
+---
+
+## ⚙️ Configuration
+
+### Default: Local ClamAV
+
+```ruby
+# config/initializers/active_storage_av_scan.rb
+ActiveStorageAvScan.queue_name = :av_scan
+ActiveStorageAvScan.scanner = ActiveStorageAvScan::Scanners::Clamav.new
+```
+
+> 💡 Check ClamAV is installed:
+> macOS → `brew install clamav`
+> Debian/Ubuntu → `sudo apt install clamav`
+
+
+
+### 💡 Custom Scanners
+
+You can plug in **any custom scanner backend** by assigning your own object that implements the same simple `scan` interface:
+
+```ruby
+class MyCustomScanner
+  include ActiveStorageAvScan::Scanner
+
+  # Must return an ActiveStorageAvScan::ScanResult
+  def scan(io:, filename:, blob: nil, **_opts)
+    # Example: call your external AV API or service
+    response = ExternalAV.scan(io)
+    if response.clean?
+      ActiveStorageAvScan::ScanResult.new(status: :clean, details: "Clean via ExternalAV")
+    else
+      ActiveStorageAvScan::ScanResult.new(
+        status: :infected,
+        virus_name: response.virus_name,
+        details: response.details
+      )
+    end
+  end
+end
+
+# Use it in your initializer
+ActiveStorageAvScan.scanner = MyCustomScanner.new
+```
+
+Any scanner that responds to:
+
+```ruby
+scan(io:, filename:, blob: nil, **opts)
+```
+
+and returns an instance of:
+
+```ruby
+ActiveStorageAvScan::ScanResult.new(status:, virus_name:, details:)
+```
+
+will work out of the box.
+
+> *Upcoming:* the gem will include first-class support for **HTTP-based external scanners** (e.g. AWS Lambda AV, REST APIs) in a future release.
+
+---
+
+## Usage
+
+### 1. Enable scanning
+
+Add `av_scanned_attachments` to your model:
+
+```ruby
+class Expense < ApplicationRecord
+  has_many_attached :receipts
+
+  av_scanned_attachments :receipts
+end
+```
+
+Every upload triggers a background scan automatically.
+
+### 2. Check results
+
+```ruby
+@expense.receipts_all_clean?     # => true / false
+@expense.receipts_any_infected?  # => true / false
+@expense.receipts_scan_statuses  # => [[attachment, "clean"], ...]
+```
+
+All results are stored in `ActiveStorageAvScan::AttachmentScan`.
+
+---
+
+## 🧠 Infection Handling
+
+You can define what happens when a file is infected:
+
+```ruby
+ActiveStorageAvScan.infected_handler = lambda do |blob, scan|
+  Rails.logger.warn "[AV] Infected file: #{blob.filename} (#{scan.virus_name})"
+  blob.attachments.each(&:purge_later)
+end
+```
+
+Handler signature:
+
+```ruby
+->(blob, scan_record) { ... }
+```
+
+---
+
+## 💻 View Helpers
+
+Add scan badges next to your file links:
+
+```erb
+<% @expense.receipts.each do |attachment| %>
+  <%= link_to attachment.filename, url_for(attachment) %>
+  <%= av_scan_badge(attachment) %>
+<% end %>
+```
+
+Default output:
+
+```html
+<span class="av-scan-badge av-scan-badge-clean">Clean</span>
+```
+You can also override classes inline for a specific badge:
+
+
+``` ruby
+  <%= av_scan_badge(attachment, css_class: "ml-2 text-xs") %>
+```
+
+Customize badge classes for Tailwind/Bootstrap/etc.:
+```ruby
+ActiveStorageAvScan.badge_class_map = {
+  "pending"  => "text-gray-700 bg-gray-200 rounded px-2 py-0.5 text-xs",
+  "clean"    => "text-green-800 bg-green-100 rounded px-2 py-0.5 text-xs",
+  "infected" => "text-red-800 bg-red-100 rounded px-2 py-0.5 text-xs",
+  "error"    => "text-yellow-800 bg-yellow-100 rounded px-2 py-0.5 text-xs"
+}
+
+```
+
+> When you run `rails g active_storage_av_scan:install`, a default
+> `app/assets/stylesheets/active_storage_av_scan.css` file is created to style scan-badges.
+> You can import it into your main stylesheet, tweak it, or replace it
+> entirely with your own styles or Tailwind/Bootstrap classes.
+
+---
+
+## 🔍 Model Reference
+
+### `ActiveStorageAvScan::AttachmentScan`
+
+| Column       | Type     | Description                                     |
+| ------------ | -------- | ----------------------------------------------- |
+| `blob_id`    | bigint   | References `ActiveStorage::Blob`                |
+| `status`     | string   | `"pending"`, `"clean"`, `"infected"`, `"error"` |
+| `scanner`    | string   | Scanner class used                              |
+| `virus_name` | string   | Virus signature name (if any)                   |
+| `details`    | text     | Raw output or error message                     |
+| `scanned_at` | datetime | Time scanned                                    |
+
+---
+
+## 🧩 Storage Compatibility
+
+Works transparently with all Active Storage services:
+
+```yaml
+amazon:
+  service: S3
+  bucket: your-bucket-<%= Rails.env %>
+
+google:
+  service: GCS
+  bucket: your-bucket-<%= Rails.env %>
+
+mirror:
+  service: Mirror
+  primary: amazon
+  mirrors: [google]
+```
+
+The scanner only ever sees an IO object (`blob.open`), regardless of backend.
+
+---
+
+## 🔒 Requirements
+
+* Ruby 3.0+
+* Rails 6.1+ (tested on 6.1, 7.0, 7.1)
+* Active Storage configured
+* ClamAV installed (`clamscan` available in PATH)
+
+---
+
+## 🧰 Development
+
+Clone and run locally:
+
+```bash
+git clone git@github.com:ajazfarhad/active_storage_av_scan.git
+cd active_storage_av_scan
+bundle install
+```
+
+You can test inside a sample Rails app:
+
+```bash
+rails g active_storage_av_scan:install
+rails db:migrate
+```
+
+Attach a file and observe the scan results in the console or DB.
+
+---
+
+## 🧭 Roadmap
+
+* [ ] HTTP / Lambda scanner backend
+* [ ] Async result polling & notifications
+* [ ] Slack / Email alert hooks
+* [ ] CLI task (`rails active_storage_av_scan:scan_all`)
+* [ ] Lightweight audit log
+* [ ] Rails Admin / ActiveAdmin integration
+* [ ] RSpec test coverage (planned for v0.2.0)
+
+---
+
+## 🧑‍💻 Contributing
+
+Contributions welcome!
+Bug reports and PRs on GitHub:
+[https://github.com/ajazfarhad/active_storage_av_scan](https://github.com/)
+
+---
+
+## 📄 License
+
+MIT License © 2025 [Ajaz Farhad]

data/lib/active_storage_av_scan/attachment_scan.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+module ActiveStorageAvScan
+  class AttachmentScan < ::ActiveRecord::Base
+    self.table_name = "active_storage_attachment_scans"
+  
+    belongs_to :blob, class_name: "ActiveStorage::Blob"
+  
+    STATUSES = %w[pending clean infected error].freeze
+    
+    STATUS_MAP = {
+      pending:  "pending",
+      clean:    "clean",
+      infected: "infected",
+      errored:  "error"
+    }.freeze
+  
+    validates :status, presence: true, inclusion: { in: STATUSES }
+  
+    STATUS_MAP.each do |name, value|
+      # scopes: .pending, .clean, .infected, .errored
+      scope name, -> { where(status: value) }
+  
+      # predicate methods: #pending?, #clean?, #infected?, #errored?
+      define_method("#{name}?") do
+        status == value
+      end
+    end
+  end
+end
+

data/lib/active_storage_av_scan/model.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActiveStorageAvScan
+  module Model
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Example usage:
+      #   av_scanned_attachments :receipts, :invoice
+      #
+      def av_scanned_attachments(*attachment_names)
+        attachment_names = attachment_names.map(&:to_sym)
+
+        # record which attachment names are protected
+        class_attribute :av_scanned_attachment_names, instance_writer: false, default: []
+        self.av_scanned_attachment_names += attachment_names
+
+        # after commit, enqueue scans for any blobs without a scan record
+        after_commit(on: %i[create update]) do
+          self.class.av_scanned_attachment_names.each do |name|
+            attachments = send(name)
+            # supports has_one_attached and has_many_attached
+            Array(attachments.attachments).each do |attachment|
+              blob = attachment.blob
+              next if ActiveStorageAvScan::AttachmentScan.exists?(blob: blob)
+
+              ActiveStorageAvScan::ScanJob.perform_later(blob.id)
+            end
+          end
+        end
+
+        attachment_names.each do |name|
+          define_method :"#{name}_all_clean?" do
+            Array(send(name).attachments).all? do |attachment|
+              scan = ActiveStorageAvScan::AttachmentScan.find_by(blob: attachment.blob)
+              scan&.clean?
+            end
+          end
+
+          define_method :"#{name}_any_infected?" do
+            Array(send(name).attachments).any? do |attachment|
+              scan = ActiveStorageAvScan::AttachmentScan.find_by(blob: attachment.blob)
+              scan&.infected?
+            end
+          end
+
+          define_method :"#{name}_scan_statuses" do
+            Array(send(name).attachments).map do |attachment|
+              scan = ActiveStorageAvScan::AttachmentScan.find_by(blob: attachment.blob)
+              [attachment, scan&.status || "pending"]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage_av_scan/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+if defined?(Rails::Railtie)
+  require "active_storage_av_scan/view_helpers"
+
+  module ActiveStorageAvScan
+    class Railtie < ::Rails::Railtie
+      initializer "active_storage_av_scan.model" do
+        ActiveSupport.on_load(:active_record) do
+          include ActiveStorageAvScan::Model
+        end
+      end
+
+      initializer "active_storage_av_scan.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include ActiveStorageAvScan::ViewHelpers
+        end
+      end
+    end
+  end
+end

data/lib/active_storage_av_scan/scan_job.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActiveStorageAvScan
+  class ScanJob < ::ActiveJob::Base
+    queue_as do
+      ActiveStorageAvScan.queue_name.presence || :default
+    end
+
+    def perform(blob_id)
+      blob = ActiveStorage::Blob.find(blob_id)
+
+      scan_record = AttachmentScan.find_or_create_by!(blob: blob) do |scan|
+        scan.status  = "pending"
+        scan.scanner = ActiveStorageAvScan.scanner&.class&.name
+      end
+
+      blob.open do |io|
+        result = ActiveStorageAvScan.scanner.scan(
+          io:       io,
+          filename: blob.filename.to_s,
+          blob:     blob
+        )
+
+        scan_record.status     = result.status.to_s
+        scan_record.virus_name = result.virus_name
+        scan_record.details    = result.details
+        scan_record.scanned_at = Time.current
+        scan_record.scanner  ||= ActiveStorageAvScan.scanner&.class&.name
+        scan_record.save!
+      end
+
+      # Run policy hook for infected files, after we've saved the record
+      if scan_record.infected? && ActiveStorageAvScan.infected_handler.respond_to?(:call)
+        safely_call_infected_handler(blob, scan_record)
+      end
+    rescue => e
+      scan_record ||= AttachmentScan.find_or_initialize_by(blob: blob)
+      scan_record.status     = "error"
+      scan_record.details    = [scan_record.details, e.message].compact.join("\n")
+      scan_record.scanned_at = Time.current
+      scan_record.save!
+      raise
+    end
+
+    private
+
+    def safely_call_infected_handler(blob, scan_record)
+      ActiveStorageAvScan.infected_handler.call(blob, scan_record)
+    rescue => e
+      # Don't let a buggy handler break the scan job
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error("[ActiveStorageAvScan] infected_handler failed for blob #{blob.id}: #{e.class} - #{e.message}")
+      end
+    end
+  end
+end

data/lib/active_storage_av_scan/scanner.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveStorageAvScan
+  class ScanResult
+    attr_reader :status, :virus_name, :details
+
+    # status: :clean, :infected, :error
+    def initialize(status:, virus_name: nil, details: nil)
+      @status     = status.to_sym
+      @virus_name = virus_name
+      @details    = details
+    end
+
+    def clean?    = status == :clean
+    def infected? = status == :infected
+    def error?    = status == :error
+  end
+
+  # Base module for scanners – implement concrete (ClamAV, HTTP/Lambda, etc.)
+  module Scanner
+    # Default interface: scanners SHOULD accept blob: but can ignore it.
+    def scan(io:, filename:, blob: nil, **_opts)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/active_storage_av_scan/scanners/clamav.rb

@@ -0,0 +1,41 @@
+require "open3"
+require "tempfile"
+
+module ActiveStorageAvScan
+  module Scanners
+    class Clamav
+      include ActiveStorageAvScan::Scanner
+
+      # Accept blob: (even though we don't use it) to keep interface compatible
+      def scan(io:, filename:, blob: nil, **_opts)
+        # io is an IO-like object or a Tempfile
+        path = io.respond_to?(:path) ? io.path : write_tempfile(io, filename)
+
+        stdout, stderr, status = Open3.capture3("clamscan", "--no-summary", path)
+
+        if status.success?
+          ScanResult.new(status: :clean)
+        else
+          # crude parsing
+          virus = stdout.to_s.split(":").last&.strip
+          ScanResult.new(
+            status:     :infected,
+            virus_name: virus,
+            details:    stdout.presence || stderr
+          )
+        end
+      rescue => e
+        ScanResult.new(status: :error, details: e.message)
+      end
+
+      private
+
+      def write_tempfile(io, filename)
+        file = Tempfile.new(["avscan", File.extname(filename)])
+        IO.copy_stream(io, file)
+        file.rewind
+        file.path
+      end
+    end
+  end
+end

data/lib/active_storage_av_scan/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveStorageAvScan
+  VERSION = "0.1.0"
+end

data/lib/active_storage_av_scan/view_helpers.rb

@@ -0,0 +1,46 @@
+# lib/active_storage_av_scan/view_helpers.rb
+# frozen_string_literal: true
+
+module ActiveStorageAvScan
+  module ViewHelpers
+    # Returns "pending", "clean", "infected", or "error" for an attachment.
+    # If there's no scan record yet, defaults to "pending".
+    def av_scan_status(attachment)
+      scan = ActiveStorageAvScan::AttachmentScan.find_by(blob: attachment.blob)
+      scan&.status || "pending"
+    end
+
+    # Renders a small badge showing scan status.
+    #
+    # Options:
+    #   label:      custom text (default: "Pending"/"Clean"/"Infected"/"Error")
+    #   css_class:  extra CSS classes to append
+    #   tag:        HTML tag to use (default: :span)
+    #
+    # Example:
+    #   <%= av_scan_badge(attachment) %>
+    #   <%= av_scan_badge(attachment, css_class: "ml-2 text-xs") %>
+    #
+    def av_scan_badge(attachment, label: nil, css_class: nil, tag: :span, **attrs)
+      status      = av_scan_status(attachment)
+      default_tag = tag || :span
+
+      text       = label || default_label_for_status(status)
+      base_class = ActiveStorageAvScan.badge_class_for(status)
+      full_class = [base_class, css_class].compact.join(" ")
+
+      content_tag(default_tag, text, { class: full_class }.merge(attrs))
+    end
+
+    private
+
+    def default_label_for_status(status)
+      case status.to_s
+      when "clean"    then "Clean"
+      when "infected" then "Infected"
+      when "error"    then "Scan error"
+      else                 "Pending scan"
+      end
+    end
+  end
+end

data/lib/active_storage_av_scan.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext"
+require "active_job"
+require "active_record"
+
+require "active_storage_av_scan/version"
+require "active_storage_av_scan/railtie"
+require "active_storage_av_scan/scanner"
+require "active_storage_av_scan/attachment_scan"
+require "active_storage_av_scan/model"
+require "active_storage_av_scan/scan_job"
+require "active_storage_av_scan/scanners/clamav"
+
+module ActiveStorageAvScan
+  # configurable scanner backend (e.g. ClamavScanner, HttpScanner, etc.)
+  mattr_accessor :scanner
+
+  # queue name used by ScanJob (falls back to :default)
+  mattr_accessor :queue_name
+
+  # mapping from status => CSS classes
+  # apps can override this in an initializer
+  mattr_accessor :badge_class_map
+  self.badge_class_map = {
+    "pending"  => "av-scan-badge av-scan-badge-pending",
+    "clean"    => "av-scan-badge av-scan-badge-clean",
+    "infected" => "av-scan-badge av-scan-badge-infected",
+    "error"    => "av-scan-badge av-scan-badge-error"
+  }
+
+  def self.badge_class_for(status)
+    badge_class_map[status.to_s] || "av-scan-badge"
+  end
+
+  # optional hook: called when a scan result is infected
+  # signature: ->(blob, attachment_scan) { ... }
+  mattr_accessor :infected_handler
+end

data/lib/generators/active_storage_av_scan/install/install_generator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module ActiveStorageAvScan
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      desc "Install ActiveStorageAvScan (migration + initializer)."
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Always use timestamped migrations
+      def self.next_migration_number(dirname)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def copy_migration
+        check_requirements!
+        migration_template "create_active_storage_attachment_scans.rb",
+        "db/migrate/create_active_storage_attachment_scans.rb"
+      end
+
+      def copy_initializer
+        # We don't strictly need the checks here again, copy_migration already ran them
+        template "initializer.rb",
+        "config/initializers/active_storage_av_scan.rb"
+      end
+
+      def copy_stylesheet
+        # For classic asset pipeline / Sprockets:
+        if File.directory?("app/assets/stylesheets")
+          copy_file "active_storage_av_scan.css",
+          "app/assets/stylesheets/active_storage_av_scan.css"
+          # For cssbundling-rails apps (app/assets/builds or app/javascript/styles):
+        elsif File.directory?("app/assets/builds")
+          copy_file "active_storage_av_scan.css",
+          "app/assets/builds/active_storage_av_scan.css"
+        else
+          say_status :warning,
+          "Could not determine stylesheets directory; please copy active_storage_av_scan.css manually if needed.",
+          :yellow
+        end
+      end
+
+
+      private
+
+      def check_requirements!
+        check_active_storage!
+        check_clamav!
+      end
+
+      def check_active_storage!
+        unless defined?(ActiveStorage::Blob)
+          say_status :error, "Active Storage does not appear to be loaded.", :red
+          say        "Add Active Storage and run `rails active_storage:install` and `rails db:migrate` first.", :red
+          raise Thor::Error, "Active Storage is required for active_storage_av_scan."
+        end
+
+        begin
+          unless ActiveRecord::Base.connection.data_source_exists?(ActiveStorage::Blob.table_name)
+            say_status :error, "Active Storage tables not found (#{ActiveStorage::Blob.table_name}).", :red
+            say        "Run `rails active_storage:install` and `rails db:migrate`.", :red
+            raise Thor::Error, "Active Storage is required for active_storage_av_scan."
+          end
+        rescue ActiveRecord::NoDatabaseError
+          # During some setup flows the DB may not exist yet – let the user handle that.
+          say_status :warning, "Skipping Active Storage DB check (database not created yet).", :yellow
+        end
+      end
+
+      def check_clamav!
+        return if ENV["ACTIVE_STORAGE_AV_SCAN_SKIP_CLAMAV_CHECK"] == "1"
+
+        # Check if `clamscan` is available in PATH
+        if system("command -v clamscan >/dev/null 2>&1")
+          say_status :ok, "ClamAV detected (`clamscan` found in PATH).", :green
+        else
+          say_status :warning, "ClamAV not detected (`clamscan` not found in PATH).", :yellow
+          say        "The default ClamAV scanner will not work until ClamAV is installed,", :yellow
+          say        "or you configure `ActiveStorageAvScan.scanner` to a different backend.", :yellow
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_storage_av_scan/install/templates/active_storage_av_scan.css

@@ -0,0 +1,30 @@
+/* Default styles for ActiveStorageAvScan badges.
+ * You can tweak or remove these in your app as needed.
+ */
+
+.av-scan-badge {
+  display: inline-block;
+  padding: 0.1rem 0.4rem;
+  border-radius: 9999px;
+  font-size: 0.75rem;
+}
+
+.av-scan-badge-clean {
+  background: #e0f7e9;
+  color: #166534;
+}
+
+.av-scan-badge-infected {
+  background: #fee2e2;
+  color: #b91c1c;
+}
+
+.av-scan-badge-pending {
+  background: #e5e7eb;
+  color: #374151;
+}
+
+.av-scan-badge-error {
+  background: #fef3c7;
+  color: #92400e;
+}

data/lib/generators/active_storage_av_scan/install/templates/create_active_storage_attachment_scans.rb

@@ -0,0 +1,16 @@
+class CreateActiveStorageAttachmentScans < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+  def change
+    create_table :active_storage_attachment_scans do |t|
+      t.references :blob, null: false, foreign_key: { to_table: :active_storage_blobs }
+      t.string :status, null: false, default: "pending"
+      t.string :scanner
+      t.string :virus_name
+      t.text :details
+      t.datetime :scanned_at
+
+      t.timestamps
+    end
+
+    add_index :active_storage_attachment_scans, :status
+  end
+end

data/lib/generators/active_storage_av_scan/install/templates/initializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Configure the scanner backend for ActiveStorageAvScan.
+#
+# You can use:
+# - ActiveStorageAvScan::Scanners::Clamav (local clamscan/clamd)
+# - ActiveStorageAvScan::Scanners::Http   (remote HTTP / Lambda-based service)
+#
+# Example ClamAV:
+# ActiveStorageAvScan.scanner = ActiveStorageAvScan::Scanners::Clamav.new
+#
+
+ActiveStorageAvScan.scanner ||= ActiveStorageAvScan::Scanners::Clamav.new

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: active_storage_av_scan
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ajaz Farhad
+bindir: exe
+cert_chain: []
+date: 2025-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: active_storage_av_scan adds background antivirus scanning to Rails Active
+  Storage attachments, with a ClamAV scanner, scan status model, view helpers, and
+  configurable infection handling.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- lib/active_storage_av_scan.rb
+- lib/active_storage_av_scan/attachment_scan.rb
+- lib/active_storage_av_scan/model.rb
+- lib/active_storage_av_scan/railtie.rb
+- lib/active_storage_av_scan/scan_job.rb
+- lib/active_storage_av_scan/scanner.rb
+- lib/active_storage_av_scan/scanners/clamav.rb
+- lib/active_storage_av_scan/version.rb
+- lib/active_storage_av_scan/view_helpers.rb
+- lib/generators/active_storage_av_scan/install/install_generator.rb
+- lib/generators/active_storage_av_scan/install/templates/active_storage_av_scan.css
+- lib/generators/active_storage_av_scan/install/templates/create_active_storage_attachment_scans.rb
+- lib/generators/active_storage_av_scan/install/templates/initializer.rb
+homepage: https://github.com/ajazfarhad/active_storage_av_scan
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ajazfarhad/active_storage_av_scan
+  changelog_uri: https://github.com/ajazfarhad/active_storage_av_scan/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Antivirus scanning for Rails Active Storage using ClamAV.
+test_files: []