How ossincn/ossimagent works
Project type and purpose
• This is the OSSIM Python “agent”:
• Exposes a Control API for remote management
• Runs inventory (LDAP, NMAP, Nagios, OCS, WMI) and monitoring (sniffer, log‐tailing, SDEE, WMI) tasks
• Parses/normalizes data, writes to a local DB, and pushes events to an OSSIM manager
File structure
• Top‐level scripts & modules:
• Agent.py / ossim-agent (main binary)
• Control*.py, Conn.py, Monitor*.py (Control & monitoring frameworks)
• InventoryTask_*.py, ControlInventory.py, ControlNmap.py… (task handlers)
• Parser*.py, Detector.py, Event*.py (data ingestion & normalization)
• Database.py, ParserDatabase.py (persistence layer)
• Output.py, MonitorHTTP.py, MonitorSocket.py (event forwarding)
• Utils, Logger, Profiler, Stats, Threshold, Watchdog (support libraries)
README for additional insights
• The README.control describes the Control API’s message format, commands (config_file_*, nmap_*), parameters, and response patterns.
• It confirms a request/response socket‐based protocol for remote management.
Main components and their interactions
a. Control Framework
• Conn.py / MonitorSocket.py: listens for incoming control requests
• Control.py: parses “control action=…” XML, dispatches to submodules
• Submodules (ControlInventory.py, ControlNmap.py, ControlSniffer.py, ControlVAScanner.py, ControlUtil.py) handle specific commands
• They spawn Task classes (InventoryTask_*, MonitorCommand.py) and stream back responses
b. Monitoring Framework
• MonitorScheduler.py: schedules periodic jobs (sniffer, log tailing, WMI polling…)
• MonitorSession.py: tracks session state for long‐running tasks
• TailFollow.py / TailFollowBookmark.py: incremental log reading
• PacketUtils.py / SessionParser.py: sniff & reassemble network sessions
c. Parsers & Detectors
• Parser*.py modules: parse Snort, FTP, JSON, SDEE, WMI, etc.
• ParserUtil.py: common parsing helpers
• Detector.py + Event/EventList.py + Threshold.py: apply detection rules and generate normalized Event objects
d. Data Layer
• Database.py: local event/inventory store (SQLite or MySQL)
• ParserDatabase.py: lookup tables for normalization (OS, service names, etc.)
e. Output & Networking
• Output.py: formats events for transmission
• MonitorHTTP.py / MonitorSocket.py: sends events to the OSSIM manager via HTTP or native socket
Architectural patterns & design principles
• Dispatcher pattern: Control.py → ControlXYZ modules
• Plugin architecture: each inventory/monitor/parser is self‐contained
• Producer/consumer & event‐driven: Scheduler → Parsers → Detector → Output
• Layered separation: API layer, orchestration/scheduler, processing/parsing, persistence, integration
Elements
• Clear labels on each component (e.g., “Control API”, “Monitor Scheduler”, “ParserSnort”)
• Solid for synchronous flows (control request → handler → response)
• Blue rectangles for API components
• Green for processing/parsing
• Purple clouds for external systems
Detail level
• Don’t lump everything into “agent.py.” Break out at minimum:
• Control API (Conn, Control, ControlXYZ)
• Scheduler & Tasks (MonitorScheduler, InventoryTask_*)
• Parsers & Detectors (Parser*, Detector, EventList)
• Database (Database, ParserDatabase)
• Output (Output, MonitorHTTP/Socket)