00001 //--------------------------------------------------------------------------
00002 // Copyright (C) 2014-2017 Cisco and/or its affiliates. All rights reserved.
00003 //
00004 // This program is free software; you can redistribute it and/or modify it
00005 // under the terms of the GNU General Public License Version 2 as published
00006 // by the Free Software Foundation. You may not use, modify or distribute
00007 // this program under any other version of the GNU General Public License.
00008 //
00009 // This program is distributed in the hope that it will be useful, but
00010 // WITHOUT ANY WARRANTY; without even the implied warranty of
00011 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00012 // General Public License for more details.
00013 //
00014 // You should have received a copy of the GNU General Public License along
00015 // with this program; if not, write to the Free Software Foundation, Inc.,
00016 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00017 //--------------------------------------------------------------------------
00018 // inspector.h author Russ Combs <rucombs@cisco.com>
00019
00020 #ifndef INSPECTOR_H
00021 #define INSPECTOR_H
00022
00023 // Inspectors are the workhorse that do all the heavy lifting between
00024 // decoding a packet and detection. There are several types that operate
00025 // in different ways. These correspond to Snort 2X preprocessors.
00026
00027 #include <atomic>
00028
00029 #include "framework/base_api.h"
00030 #include "main/thread.h"
00031
00032 struct Packet;
00033 struct SnortConfig;
00034
00035 typedef int16_t ServiceId;
00036
00037 // this is the current version of the api
00038 #define INSAPI_VERSION ((BASE_API_VERSION << 16) | 0)
00039
00040 struct InspectionBuffer
00041 {
00042 enum Type
00043 {
00044 // FIXIT-L file data is tbd
00045 IBT_KEY, IBT_HEADER, IBT_BODY, IBT_FILE, IBT_ALT, IBT_MAX
00046 };
00047 const uint8_t* data;
00048 unsigned len;
00049 };
00050
00051 struct InspectApi;
00052
00053 //-------------------------------------------------------------------------
00054 // api for class
00055 //-------------------------------------------------------------------------
00056
00057 class SO_PUBLIC Inspector
00058 {
00059 public:
00060 // main thread functions
00061 virtual ~Inspector();
00062
00063 // access external dependencies here
00064 // return verification status
00065 virtual bool configure(SnortConfig*) { return true; }
00066 virtual void show(SnortConfig*) { }
00067 virtual void update(SnortConfig*, const char*) { }
00068
00069 // packet thread functions
00070 // tinit, tterm called on default policy instance only
00071 virtual void tinit() { } // allocate configurable thread local
00072 virtual void tterm() { } // purge only, deallocate via api
00073
00074 // screen incoming packets; only liked packets go to eval
00075 // default filter is per api proto / paf
00076 virtual bool likes(Packet*);
00077
00078 // clear is a bookend to eval() for the active service inspector
00079 // clear is called when Snort is done with the previously eval'd
00080 // packet to release any thread-local or flow-based data
00081 virtual void eval(Packet*) = 0;
00082 virtual void clear(Packet*) { }
00083
00084 virtual void meta(int, const uint8_t*) { }
00085 virtual int exec(int, void*) { return 0; }
00086
00087 // framework support
00088 unsigned get_ref(unsigned i) { return ref_count[i]; }
00089 void set_ref(unsigned i, unsigned r) { ref_count[i] = r; }
00090
00091 void add_ref() { ++ref_count[slot]; }
00092 void rem_ref() { --ref_count[slot]; }
00093
00094 bool is_inactive();
00095
00096 void set_service(ServiceId id) { srv_id = id; }
00097 ServiceId get_service() { return srv_id; }
00098
00099 // for well known buffers
00100 // well known buffers may be included among generic below,
00101 // but they must be accessible from here
00102 virtual bool get_buf(InspectionBuffer::Type, Packet*, InspectionBuffer&)
00103 { return false; }
00104
00105 // for generic buffers
00106 // key is listed in api buffers
00107 // id-1 is zero based index into buffers array
00108 unsigned get_buf_id(const char* key);
00109 virtual bool get_buf(const char* key, Packet*, InspectionBuffer&);
00110 virtual bool get_buf(unsigned /*id*/, Packet*, InspectionBuffer&)
00111 { return false; }
00112
00113 virtual bool get_fp_buf(InspectionBuffer::Type ibt, Packet* p, InspectionBuffer& bf)
00114 { return get_buf(ibt, p, bf); }
00115
00116 // IT_SERVICE only
00117 virtual class StreamSplitter* get_splitter(bool to_server);
00118
00119 void set_api(const InspectApi* p)
00120 { api = p; }
00121
00122 const InspectApi* get_api()
00123 { return api; }
00124
00125 const char* get_name();
00126
00127 public:
00128 static unsigned max_slots;
00129 static THREAD_LOCAL unsigned slot;
00130
00131 protected:
00132 // main thread functions
00133 Inspector(); // internal init only at this point
00134
00135 private:
00136 const InspectApi* api;
00137 std::atomic_uint* ref_count;
00138 ServiceId srv_id;
00139 };
00140
00141 template <typename T>
00142 class InspectorData : public Inspector
00143 {
00144 public:
00145 InspectorData(T* t)
00146 { data = t; }
00147
00148 ~InspectorData() override
00149 { delete data; }
00150
00151 void eval(Packet*) override { }
00152
00153 T* data;
00154 };
00155
00156 enum InspectorType
00157 {
00158 IT_PASSIVE, // config only, or data consumer
00159 IT_BINDER, // maps config to traffic
00160 IT_WIZARD, // guesses service inspector
00161 IT_PACKET, // processes raw packets
00162 IT_NETWORK, // process packets w/o service
00163 IT_STREAM, // flow tracking and reassembly
00164 IT_SERVICE, // reassemble and process service PDUs
00165 IT_PROBE, // process all packets after above
00166 IT_MAX
00167 };
00168
00169 typedef Inspector* (* InspectNew)(Module*);
00170 typedef void (* InspectDelFunc)(Inspector*);
00171 typedef void (* InspectFunc)();
00172 typedef class Session* (* InspectSsnFunc)(class Flow*);
00173
00174 struct InspectApi
00175 {
00176 BaseApi base;
00177 InspectorType type;
00178 uint16_t proto_bits;
00179
00180 const char** buffers; // null terminated list of exported buffers
00181 const char* service; // nullptr when type != IT_SERVICE
00182
00183 InspectFunc pinit; // plugin init
00184 InspectFunc pterm; // cleanup pinit()
00185 InspectFunc tinit; // thread local init
00186 InspectFunc tterm; // cleanup tinit()
00187 InspectNew ctor; // instantiate inspector from Module data
00188 InspectDelFunc dtor; // release inspector instance
00189 InspectSsnFunc ssn; // get new session tracker
00190 InspectFunc reset; // clear stats
00191 };
00192
00193 inline const char* Inspector::get_name()
00194 { return api->base.name; }
00195
00196 #endif
00197
END OF CODE