[Up]: Storage API : AntiVirus Scan

AntiVirus Scan

Script path: /storage/bin/api/av_scan.cgi

Description:  Scan a file or entire folder for virus signature

INPUT (via GET or POST)

   sid => the authenticated session id  (must be valid)

   path => the file or folder to scan on.

        path must specify an existing item.
        The trailing "/" is not significant here even for folders.

   ofmt => json  | jsonp

	output the response in JSON object.
	"json" for formatting with minimal white space, and
	"jsonp" for pretty formatting for easier human readability.
	By default, for compatibility with legacy calls, non-JSON response is produced.

OUTPUT (content-type: text/plain)

   Successful processing of call:

	File or files in folder are all ok, no virus signature detected.

		Legacy output:

		true <tab> 0

		Equivalent JSON output:
		{
		  "status" : true,
		  "scan_result" : 0,
		  "comment" : "No viral signature detected."
		}


	One or more files has viral signature, and the filename (or relative filename) and the virus name
	is listed one on each following line, with <tab> separating the filename from the virus name

		Legacy output:

		true <tab> 1
		basename.ext  <tab>  Virus.Name1
		relative/path/to/basename2.ext  <tab>  Virus.Name2

		Equivalent JSON output:
		{
		  "status" : true,
		  "scan_result" : 1,
		  "comment" : "Viral signature detected.",
		  "infected_list" : 
			[
		  	  { "path" : "/full/path/to/basename.ext", "virusname" : "Virus.Name1" },
		  	  { "path" : "/another/full/path/to/basename2.ext", "virusname" : "Virus.Name2" }
			]
		}


   General failed call:

		Legacy output:

		false <tab> (the error message)

		Equivalent JSON output:
		{
		  "status" : false,
		  "errmsg" : "(reason for the failure)"
		}


   Example outputs (first legacy format, followed by JSON format):

   ##### if the file or folder is non-existent

	false	Item does not exist.

	{
	  "status" : false,
	  "errmsg" : "Item does not exist."
	}


   ##### if no file is infected

	true	0

	{
	  "status" : true,
	  "scan_result" : 0,
	  "comment" : "No viral signature detected."
	}

   ##### if the file (or at least one file in a folder) is infected

	true	1
	virus-infected-file-vwvzgu.exe	Trojan.Autoit-77

	{
	  "status" : true,
	  "scan_result" : 1,
	  "comment" : "Viral signature detected.",
	  "infected_list" : 
		[
		  { "path" : "/Private/vcollection/virus-infected-file-vwvzgu.exe", "virusname" : "Trojan.Autoit-77" }
		]
	}


   #####  in this case four files (in a folder) have viral signature

	true	1
	eicar.bin	Eicar-Test-Signature
	eicarcom2.zip	Eicar-Test-Signature
	subfolder/eicar.com.txt	Eicar-Test-Signature
	subfolder/eicar_com.zip	Eicar-Test-Signature

	  This last example means a folder was scanned. Suppose path=/Private/Docs is the folder, then it means
	    /Private/Docs/eicar.bin
	    /Private/Docs/eicarcom2.zip
	    /Private/Docs/subfolder/eicar.com.txt
	    /Private/Docs/subfolder/eicar_com.zip
	  are infected.


	{
	  "status" : true,
	  "scan_result" : 1,
	  "comment" : "Viral signature detected.",
	  "infected_list" : 
		[
		  { "path" : "/Private/Docs/eicar.bin", "virusname" : "Eicar-Test-Signature" },
		  { "path" : "/Private/Docs/eicarcom2.zip", "virusname" : "Eicar-Test-Signature" },
		  { "path" : "/Private/Docs/subfolder/eicar.com.txt", "virusname" : "Eicar-Test-Signature" },
		  { "path" : "/Private/Docs/subfolder/eicar_com.zip", "virusname" : "Eicar-Test-Signature" }
		]
	}

   In all cases, appropriate HTTP header status codes are also returned e.g. 200 OK, 401 Invalid user
   profile, etc.

   BTW, the "virus name" Eicar-Test-Signature is NOT a real virus, but a harmless signature decided by
   European Institute for Computer Antivirus Research (EICAR) that is accepted by anti-virus developers
   to have a way to safely test positive detection without the worry of handling actual virus.
   You may google EICAR and EICAR Test Signature for more info. If you need the test files I have
   the in my collection. :-)