Lookup Binary

Instructions

Implementation Reference

• mcp_server/server.py:84-139 (handler)

  Main handler function for the detection_lookup_binary tool. It takes a filename, strips any path, searches LOLBAS (Windows) and GTFOBins (Linux) datasets, and returns found/not-found with risk, categories, MITRE IDs, and description.

  def detection_lookup_binary(filename: str) -> dict[str, Any]:
      """Check if a binary is a known LOLBAS (Windows) or GTFOBins (Linux) living-off-the-land binary.
  
      Provide the filename (e.g., 'certutil.exe', 'curl', 'python').
      Returns risk level, abuse categories, MITRE ATT&CK technique IDs, description, and source.
      Searches both LOLBAS (Windows) and GTFOBins (Linux) datasets.
      If not found in either, returns {found: false} with a suggestion.
      """
      filename_lower = filename.lower().strip()
      # Strip path if provided
      if "\\" in filename_lower or "/" in filename_lower:
          filename_lower = filename_lower.replace("\\", "/").split("/")[-1]
  
      results = []
  
      # Search LOLBAS (Windows)
      for row in _get_lolbas():
          if row.get("filename", "").lower() == filename_lower:
              results.append({
                  "source": "lolbas",
                  "binary_name": row.get("binary_name", ""),
                  "primary_path": row.get("primary_path", ""),
                  "categories": row.get("categories", "").split("|") if row.get("categories") else [],
                  "mitre_ids": row.get("mitre_ids", "").split("|") if row.get("mitre_ids") else [],
                  "risk": row.get("risk", ""),
                  "description": row.get("description", ""),
              })
  
      # Search GTFOBins (Linux)
      for row in _get_gtfobins():
          if row.get("filename", "").lower() == filename_lower:
              results.append({
                  "source": "gtfobins",
                  "binary_name": row.get("binary_name", ""),
                  "primary_path": row.get("primary_path", ""),
                  "categories": row.get("categories", "").split("|") if row.get("categories") else [],
                  "mitre_ids": row.get("mitre_ids", "").split("|") if row.get("mitre_ids") else [],
                  "risk": row.get("risk", ""),
                  "description": row.get("description", ""),
              })
  
      if not results:
          return {
              "found": False,
              "filename": filename_lower,
              "suggestion": (
                  "Binary not in LOLBAS or GTFOBins datasets. "
                  "Try without the file extension (e.g., 'notepad' instead of 'notepad.exe'), "
                  "or use detection_search to search by keyword."
              ),
          }
  
      # If found in one source, return that; if both, return all matches
      if len(results) == 1:
          return {"found": True, **results[0]}
      return {"found": True, "matches": results}

• mcp_server/server.py:75-83 (registration)

  Registration of detection_lookup_binary as an MCP tool via @mcp.tool decorator with annotations for title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

  @mcp.tool(
      annotations={
          "title": "Lookup Binary",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False,
      },
  )

• mcp_server/server.py:34-41 (helper)

  _load_csv helper function used by caches to load CSV lookup files from the lookups/ directory. Called indirectly by detection_lookup_binary via _get_lolbas() and _get_gtfobins().

  def _load_csv(filename: str) -> list[dict[str, str]]:
      """Load a CSV lookup file and return rows as list of dicts."""
      filepath = LOOKUPS_DIR / filename
      if not filepath.exists():
          return []
      with open(filepath, "r", encoding="utf-8") as f:
          return list(csv.DictReader(f))

• mcp_server/server.py:54-58 (helper)

  _get_lolbas helper that caches and returns LOLBAS CSV data. Used by detection_lookup_binary to search for Windows binaries.

  def _get_lolbas() -> list[dict[str, str]]:
      global _lolbas_cache
      if _lolbas_cache is None:
          _lolbas_cache = _load_csv("lolbas_binaries.csv")
      return _lolbas_cache

• mcp_server/server.py:68-72 (helper)

  _get_gtfobins helper that caches and returns GTFOBins CSV data. Used by detection_lookup_binary to search for Linux binaries.

  def _get_gtfobins() -> list[dict[str, str]]:
      global _gtfobins_cache
      if _gtfobins_cache is None:
          _gtfobins_cache = _load_csv("gtfobins.csv")
      return _gtfobins_cache