diff --git a/doc/scapy.1 b/doc/scapy.1 new file mode 100644 index 000000000..8c2b8663d --- /dev/null +++ b/doc/scapy.1 @@ -0,0 +1,198 @@ +.TH SCAPY 1 "May 12, 2003" +.SH NAME +scapy \- Interactive packet manipulation tool +.SH SYNOPSIS +.B scapy +.RI [ options ] +.SH DESCRIPTION +This manual page documents briefly the +.B scapy +tool. +.PP +\fBscapy\fP is a powerful interactive packet manipulation tool, +packet generator, network scanner, network discovery, packet sniffer, +etc. It can for the moment replace hping, parts of nmap, arpspoof, arp-sk, +arping, tcpdump, tshark, p0f, ... +.PP +\fBscapy\fP uses the python interpreter as a command board. That means that +you can use directly python language (assign variables, use loops, +define functions, etc.) If you give a file as parameter when you run +\fBscapy\fP, your session (variables, functions, intances, ...) will be saved +when you leave the interpretor, and restored the next time you launch +\fBscapy\fP. +.PP +The idea is simple. Those kind of tools do two things : sending packets +and receiving answers. That's what \fBscapy\fP does : you define a set of +packets, it sends them, receives answers, matches requests with answers +and returns a list of packet couples (request, answer) and a list of +unmatched packets. This has the big advantage over tools like nmap or +hping that an answer is not reduced to (open/closed/filtered), but is +the whole packet. +.PP +On top of this can be build more high level functions, for example one +that does traceroutes and give as a result only the start TTL of the +request and the source IP of the answer. One that pings a whole network +and gives the list of machines answering. One that does a portscan and +returns a LaTeX report. + +.SH OPTIONS +Options for scapy are: +.TP +\fB\-h\fR +display usage +.TP +\fB\-d\fR +increase log verbosity. Can be used many times. +.TP +\fB\-s\fR FILE +use FILE to save/load session values (variables, functions, intances, ...) +.TP +\fB\-p\fR PRESTART_FILE +use PRESTART_FILE instead of $HOME/.scapy_prestart.py as pre-startup file +.TP +\fB\-P\fR +do not run prestart file +.TP +\fB\-c\fR STARTUP_FILE +use STARTUP_FILE instead of $HOME/.scapy_startup.py as startup file +.TP +\fB\-C\fR +do not run startup file + +.SH COMMANDS +Only the vital commands to begin are listed here for the moment. +.TP +\fBls()\fR +lists supported protocol layers. If a protocol layer is given as parameter, lists its fields and types of fields. +.TP +\fBlsc()\fR +lists some user commands. If a command is given as parameter, its documentation is displayed. +.TP +\fBconf\fR +this object contains the configuration. + +.SH FILES +\fB$HOME/.scapy_prestart.py\fR +This file is run before scapy core is loaded. Only the \fb\conf\fP object +is available. This file can be used to manipulate \fBconf.load_layers\fP +list to choose which layers will be loaded: + +.nf +conf.load_layers.remove("bluetooth") +conf.load_layers.append("new_layer") +.fi + +\fB$HOME/.scapy_startup.py\fR +This file is run after scapy is loaded. It can be used to configure +some of the scapy behaviors: + +.nf +conf.prog.pdfreader="xpdf" +split_layers(UDP,DNS) +.fi + +.SH EXAMPLES + +More verbose examples are available at +http://www.secdev.org/projects/scapy/demo.html +Just run \fBscapy\fP and try the following commands in the interpreter. + +.LP +Test the robustness of a network stack with invalid packets: +.nf +sr(IP(dst="172.16.1.1", ihl=2, options="\verb$\x02$", version=3)/ICMP()) +.fi + +.LP +Packet sniffing and dissection (with a bpf filter or thetereal-like output): +.nf +a=sniff(filter="tcp port 110") +a=sniff(prn = lambda x: x.display) +.fi + +.LP +Sniffed packet reemission: +.nf +a=sniff(filter="tcp port 110") +sendp(a) +.fi + +.LP +Pcap file packet reemission: +.nf +sendp(rdpcap("file.cap")) +.fi + +.LP +Manual TCP traceroute: +.nf +sr(IP(dst="www.google.com", ttl=(1,30))/TCP(seq=RandInt(), sport=RandShort(), dport=dport) +.fi + +.LP +Protocol scan: +.nf +sr(IP(dst="172.16.1.28", proto=(1,254))) +.fi + +.LP +ARP ping: +.nf +srp(Ether(dst="ff:ff:ff:ff:ff:ff")/ARP(pdst="172.16.1.1/24")) +.fi + +.LP +ACK scan: +.nf +sr(IP(dst="172.16.1.28")/TCP(dport=(1,1024), flags="A")) +.fi + +.LP +Passive OS fingerprinting: +.nf +sniff(prn=prnp0f) +.fi + +.LP +Active OS fingerprinting: +.nf +nmap_fp("172.16.1.232") +.fi + + +.LP +ARP cache poisonning: +.nf +sendp(Ether(dst=tmac)/ARP(op="who-has", psrc=victim, pdst=target)) +.fi + +.LP +Reporting: +.nf +report_ports("192.168.2.34", (20,30)) +.fi + +.SH SEE ALSO + +.nf +https://github.com/secdev/scapy +https://scapy.readthedocs.io/en/latest/ +.fi + +.SH BUGS +Does not give the right source IP for routes that use interface aliases. + +May miss packets under heavy load. + +Session saving is limited by Python ability to marshal objects. As a +consequence, lambda functions and generators can't be saved, which seriously +reduce usefulness of this feature. + +BPF filters don't work on Point-to-point interfaces. + + +.SH AUTHOR +Philippe Biondi +.PP +This manual page was written by Alberto Gonzalez Iniesta +and Philippe Biondi. diff --git a/doc/scapy.1.gz b/doc/scapy.1.gz deleted file mode 100644 index 042526a55..000000000 Binary files a/doc/scapy.1.gz and /dev/null differ diff --git a/setup.py b/setup.py index fed246919..801a7aaf4 100755 --- a/setup.py +++ b/setup.py @@ -63,7 +63,7 @@ setup( 'scapy/tools', ], scripts=SCRIPTS, - data_files=[('share/man/man1', ["doc/scapy.1.gz"])], + data_files=[('share/man/man1', ["doc/scapy.1"])], package_data={ 'scapy': ['VERSION'], },