I work on a cloud telephony product ReceptionMonk. One feature lets a business owner upload their own audio for the phone menu: "Press 1 for sales, press 2 for support." Those files end up on the telephony server and play to every caller.

That means a stranger can send a file that lands on a server that talks to the phone network. So every upload goes through a virus scanner before it is stored. This post is about how that scanner gate is built in Go, and one decision we got wrong the first time.

The problem with "just call the scanner"

The first version of most upload scanning looks like this:

status, _ := scanner.Scan(file) if status == "infected" { return errors.New("virus found") } save(file) 

Read it again and ask: what happens when the scanner is down?

status is empty, it is not "infected", and the file gets saved. The scanner fails, and the upload succeeds. That is called failing open, and it means your protection disappears exactly when something is already going wrong.

We had two upload paths that needed scanning: identity documents and IVR audio. I wanted both to use one gate, so a third upload path added next year could not quietly skip it.

Three outcomes, not two

The core idea: a scan has three possible results, and only one of them lets the file through.

Scanner result What the user sees File stored?
Clean Upload succeeds Yes
Infected 400: "the file was rejected because the virus scanner reported malware" No
Could not scan (scanner missing, unreachable, timed out, or returned an error) 503 with Retry-After: "please try again in a few minutes" No

The third row is the important one. "I could not check this file" is treated as "no", and the user gets an honest, retryable error instead of a silent success.

In Go, that becomes two sentinel errors:

var ( ErrInfected = errors.New("uploadscan: file rejected by virus scanner") ErrScanUnavailable = errors.New("uploadscan: virus scanner unavailable") ) 

And the gate returns nil only for a clean verdict:

// ScanFileAt returns nil only for a clean verdict. // Callers must reject the upload on any non-nil error. func (g *Gate) ScanFileAt(ctx context.Context, path string, meta Meta) (Result, error) { result, err := g.scan(ctx, path, meta) g.record(ctx, meta, result) // every attempt gets an audit row if errors.Is(err, ErrInfected) { g.alerter.VirusDetected(ctx, meta, result.Signature) } return result, err } 

The classification itself is a switch with a default that fails closed. If ClamAV ever returns a status I did not plan for, the file is rejected:

switch { case scanErr != nil || status == StatusError: return Result{Status: StatusError}, ErrScanUnavailable case status == StatusClean: return Result{Status: StatusClean}, nil case status == StatusInfected: return Result{Status: StatusInfected, Signature: sig}, ErrInfected default: // unknown status: treat as "could not scan" return Result{Status: StatusError}, ErrScanUnavailable } 

The scan also runs under context.WithTimeout, so a hung scanner turns into ErrScanUnavailable instead of a request that never ends.

Where the scan sits in the upload

Order matters as much as the scan. For audio, the handler does this:

  1. Stream the upload to a temporary file, with a size cap.
  2. Check that it really is audio (parse it, read the duration). A file named .wav with broken chunks is rejected before it costs a scan.
  3. Scan the temporary file.
  4. Only on a clean verdict, copy it into the telephony sound directory, using a temp file plus os.Rename so a half-written file is never visible.

Nothing touches the directory the phone system reads from until the scanner says clean.

The handler code stays small because the gate does the thinking:

_, err := h.scanGate.ScanFileAt(ctx, tempPath, uploadscan.Meta{ Context: "ivr_audio", CompanyID: tenantID, Filename: originalName, }) if errors.Is(err, uploadscan.ErrInfected) { return badRequest("the file was rejected because the virus scanner reported malware") } if err != nil { c.Response().Header().Set("Retry-After", "60") return serviceUnavailable("virus scanning is temporarily unavailable, so the file was not saved; please try again in a few minutes") } // clean: safe to store 

An audit row for every scan

Every scan attempt writes a row to an upload_scan table (it is an Ent schema in our case): which upload path, which company and user, the original filename, where the file would be stored, the result, the virus signature if any, and when it was scanned.

This answered questions I did not expect to get:

  • "Was this customer's file actually scanned?" Look it up.
  • "How often is the scanner unavailable?" Count the scan_error rows per day.
  • "Did we block anything last month?" Filter by infected.

If writing the row fails, the gate logs it and still returns the real verdict. A broken audit table should not let an infected file through, and it should not block a clean one either.

Alerts that fire once per detection

When a file is infected, the gate tells an admin by email (and, later, our error tracker). The alert key is built from the upload context, the company, the stored reference and the signature. Every real detection alerts, but a retried dispatch of the same detection does not send the email twice.

The logs carry IDs and the filename, never the file content.

The mistake: we shipped fail-open first

Here is the honest part. Our first version did fail open. The reasoning sounded fine at the time: "If ClamAV is down, customers can't upload greetings, and that's a bad experience."

A reviewer pushed back in code review, and they were right. The original requirement said uploads must be scanned. A gate that lets files through whenever the scanner is unhealthy does not meet that requirement. It only meets it on good days.

We switched to fail-closed, and in practice the "bad experience" is small: the user sees a clear message, waits a minute, and tries again. That is a much better trade than a file nobody checked sitting on a phone server.

Testing it without ClamAV running

The gate depends on a tiny interface instead of the real ClamAV client:

type streamScanner interface { ScanStream(ctx context.Context, r io.Reader) (ScanStatus, string, error) } 

So the tests inject a fake scanner and check every row of the table above: clean stores the file, infected returns ErrInfected and fires exactly one alert, and each failure mode (no scanner, connection error, timeout, unknown status) returns ErrScanUnavailable and stores nothing. The recorder and alerter are interfaces too, so tests can assert that an audit row was written for every case.

What I would tell myself before starting

  • Write down what happens when the dependency is down before writing the happy path.
  • Return nil for exactly one outcome. Everything else is an error.
  • Put the check in one shared place, so new upload paths get it for free.
  • Record every attempt. You will want the data the first time someone asks "was this scanned?"

I'm building this as part of ReceptionMonk, an AI receptionist and cloud phone system for businesses in India. I write about the Go, telephony and AI problems we run into along the way, so follow along if that's your kind of thing.