File Analysis Module

The File Analysis module allows you to extract metadata, generate hashes, and assess risk indicators from any supported file. It is useful for validating file integrity or performing lightweight checks before running a full threat scan.

---

Analyze a File

Use the file.analyze() method to extract metadata and hash information.

JavaScript

const details = await shield.file.analyze("document.pdf");
console.log(details);

Python

details = shield.analyze_file("document.pdf")
print(details)

---

Response Structure

A typical analysis response looks like:

{
  "sha256": "d4c3b2e1f7a9...",
  "mimeType": "application/pdf",
  "size": 58321,
  "risk": "low",
  "metadata": {
    "title": "Invoice",
    "author": "Unknown"
  }
}

---

Field Descriptions

Field	Description
sha256	File hash for integrity checks and threat lookups.
mimeType	Detected file type.
size	File size in bytes.
risk	Quick risk estimate (low, medium, high).
metadata	Optional extracted details such as author, title, or structural info.

---

Hash Lookup

Instead of uploading a file, you can quickly check if CyberShield has seen a file before using its hash.

JavaScript

const lookup = await shield.file.hashLookup("e3b0c44298fc1c...");
console.log(lookup.exists);

Python

lookup = shield.hash_lookup("e3b0c44298fc1c...")
print(lookup["exists"])

---

Hash Lookup Response

{
  "exists": true,
  "firstSeen": "2025-01-10T09:12:14Z",
  "risk": "medium"
}

---

Error Handling

Common errors in file analysis:

• File is corrupted
• Unsupported file type
• File path not found
• User does not have permission to read the file

Example (JavaScript)

try {
  const info = await shield.file.analyze("notes.tmp");
} catch (err) {
  console.error("Analysis failed:", err.message);
}

---

Next Step

Continue to the next SDK module:

• System Monitor