Skip to content

Commit f46f544

Browse files
HubTouHubTou
authored
Add files via upload
1 parent b696190 commit f46f544

13 files changed

+1474
-0
lines changed

‎License

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Copyright 2023+ Hubert Tournier
2+
3+
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
4+
5+
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
6+
7+
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
8+
9+
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
10+
11+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎Makefile

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
NAME=vuxml
2+
SOURCES=src/${NAME}/__init__.py src/${NAME}/main.py src/${NAME}/library.py
3+
4+
# Default action is to show this help message:
5+
.help:
6+
@echo "Possible targets:"
7+
@echo " check-code Verify PEP 8 compliance (lint)"
8+
@echo " check-security Verify security issues (audit)"
9+
@echo " check-unused Find unused code"
10+
@echo " check-version Find required Python version"
11+
@echo " check-sloc Count Single Lines of Code"
12+
@echo " checks Make all the previous tests"
13+
@echo " format Format code"
14+
@echo " package Build package"
15+
@echo " upload-test Upload the package to TestPyPi"
16+
@echo " upload Upload the package to PyPi"
17+
@echo " distclean Remove all generated files"
18+
19+
check-code: /usr/local/bin/pylint
20+
-pylint ${SOURCES}
21+
22+
lint: check-code
23+
24+
check-security: /usr/local/bin/bandit
25+
-bandit -r ${SOURCES}
26+
27+
audit: check-security
28+
29+
check-unused: /usr/local/bin/vulture
30+
-vulture --sort-by-size ${SOURCES}
31+
32+
check-version: /usr/local/bin/vermin
33+
-vermin ${SOURCES}
34+
35+
check-sloc: /usr/local/bin/pygount
36+
-pygount --format=summary .
37+
38+
checks: check-code check-security check-unused check-version check-sloc
39+
40+
format: /usr/local/bin/black
41+
black ${SOURCES}
42+
43+
love:
44+
@echo "Not war!"
45+
46+
man/${NAME}.1.gz: man/${NAME}.1
47+
@gzip -k9c man/${NAME}.1 > man/${NAME}.1.gz
48+
49+
man/${NAME}.3.gz: man/${NAME}.3
50+
@gzip -k9c man/${NAME}.3 > man/${NAME}.3.gz
51+
52+
package: man/${NAME}.1.gz man/${NAME}.3.gz
53+
python -m build
54+
55+
upload-test:
56+
python -m twine upload --repository testpypi dist/*
57+
58+
upload:
59+
python -m twine upload dist/*
60+
61+
distclean:
62+
rm -rf build dist src/*.egg-info man/${NAME}.1.gz man/${NAME}.3.gz
63+

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ This repository includes a command-line utility:
1515

1616
And a Python library:
1717
* [vuxml(3)](https://github.com/HubTou/vuxml/blob/main/VUXML.3.md) - FreeBSD VuXML library
18+

‎TODO.md

+1
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@ into account when checking if a vulnerable Python package is also a vulnerable F
1010

1111
## Other possible features
1212
* Disabling color output.
13+

‎VUXML.1.md

+1
Original file line numberDiff line numberDiff line change
@@ -131,3 +131,4 @@ This utility is available under the [3-clause BSD license](https://opensource.or
131131
[PORTREVISION and PORTEPOCH](https://people.freebsd.org/~olivierd/porters-handbook/makefile-naming.html) (ie. software versions ending with "\_number" or ",number")
132132
are not taken into account when checking if a vulnerable Python package is also a vulnerable FreeBSD port.
133133
I would have to develop my own versions comparison library in order to handle that (well, maybe one day :-) ).
134+

‎VUXML.3.md

+1
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,4 @@ This library is available under the [3-clause BSD license](https://opensource.or
109109
[PORTREVISION and PORTEPOCH](https://people.freebsd.org/~olivierd/porters-handbook/makefile-naming.html) (ie. software versions ending with "\_number" or ",number")
110110
are not taken into account when checking if a vulnerable Python package is also a vulnerable FreeBSD port.
111111
I would have to develop my own versions comparison library in order to handle that (well, maybe one day :-) ).
112+

‎man/vuxml.1

+217
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
.Dd March 19, 2023
2+
.Dt VUXML 1
3+
.Os
4+
.Sh NAME
5+
.Nm vuxml
6+
.Nd FreeBSD VuXML query tool
7+
.Sh SYNOPSIS
8+
.Nm
9+
.Op Fl -desc|-D
10+
.Op Fl -id|-i Ar VID
11+
.Op Fl -topic|-t Ar RE
12+
.Op Fl -keyword|-k Ar RE
13+
.Op Fl -package|-p Ar PID
14+
.Op Fl -re-names|-R
15+
.Op Fl -sources|-s
16+
.Op Fl -ref|-r Ar RID
17+
.Op Fl -discovery|-d Ar DATE
18+
.Op Fl -entry|-e Ar DATE
19+
.Op Fl -modified|-m Ar DATE
20+
.Op Fl -debug
21+
.Op Fl -help|-?
22+
.Op Fl -version
23+
.Op Fl -
24+
.Sh DESCRIPTION
25+
The
26+
.Nm
27+
utility provides easy and flexible ways to query the FreeBSD VuXML database of security issues in FreeBSD and its ports collection.
28+
.Pp
29+
You can search or explore the database:
30+
.Bl -bullet
31+
.It
32+
by vulnerability ID (with the
33+
.Op Fl -id|-i
34+
option),
35+
.It
36+
by regular expression in topics (with the
37+
.Op Fl -topic|-t
38+
option),
39+
.It
40+
by regular expression in topics and descriptions (with the
41+
.Op Fl -keyword|-k
42+
option),
43+
.It
44+
by package name or package name and version (with the
45+
.Op Fl -package|-p
46+
option),
47+
.Bl -bullet
48+
.It
49+
the package name can be treated as a regular expression (with the
50+
.Op Fl -re-names|-R
51+
option),
52+
.El
53+
.It
54+
by reference source, reference source and ID, or ID (with the
55+
.Op Fl -ref|-r
56+
option),
57+
.Bl -bullet
58+
.It
59+
existing sources can be listed (with the
60+
.Op Fl -sources|-s
61+
option),
62+
.El
63+
.It
64+
by discovery, entry or modification dates (with the
65+
.Op Fl -discovery|-d ,
66+
.Op Fl -entry|-e
67+
or
68+
.Op Fl -modified|-m
69+
options),
70+
.Bl -bullet
71+
.It
72+
these dates can be a specific day, month or year.
73+
.El
74+
.El
75+
.Pp
76+
For all these queries the detailed description is not printed, unless you use the
77+
.Op Fl -desc|-d
78+
option to render the HTML description as text.
79+
.Pp
80+
For the package and reference queries, the package and version, or reference source and ID, are separated using the '~' character.
81+
.Pp
82+
All the options can be used several times and their results are cumulative (ie. treated as logical OR).
83+
.Ss OPTIONS
84+
.Op Fl -desc|-D
85+
Print description
86+
.Pp
87+
.Op Fl -id|-i Ar VID
88+
Search for the specified Vulnerability ID
89+
.Pp
90+
.Op Fl -topic|-t Ar RE
91+
Search for the specified regex in topics
92+
.Pp
93+
.Op Fl -keyword|-k Ar RE
94+
Search for the specified regex in topics and desc.
95+
.Pp
96+
.Op Fl -package|-p Ar PID
97+
Search for the specified name in affected packages. PID can also be name~version
98+
.Pp
99+
.Op Fl -re-names|-R
100+
The name part of a PID is a regex
101+
.Pp
102+
.Op Fl -sources|-s
103+
List references sources
104+
.Pp
105+
.Op Fl -ref|-r Ar RID
106+
Search for the specified ID in references. RID can also be source~, source~ID
107+
.Pp
108+
.Op Fl -discovery|-d Ar DATE
109+
Search for the specified date in discovery dates
110+
.Pp
111+
.Op Fl -entry|-e Ar DATE
112+
Search for the specified date in entry dates
113+
.Pp
114+
.Op Fl -modified|-m Ar DATE
115+
Search for the specified date in modified dates. DATE can be YYYY-MM-DD, YYYY-MM or YYYY
116+
.Pp
117+
.Op Fl -debug
118+
Enable debug mode
119+
.Pp
120+
.Op Fl -help|-?
121+
Print usage and this help message and exit
122+
.Pp
123+
.Op Fl -version
124+
Print version and exit
125+
.Pp
126+
.Op Fl -
127+
Options processing terminator
128+
.Sh ENVIRONMENT
129+
The
130+
.Ev VUXML_DEBUG
131+
environment variable can be set to any value to enable debug mode.
132+
.Pp
133+
The
134+
.Ev LOCALAPPDATA
135+
and
136+
.Ev TMP
137+
environment variables under Windows, and
138+
.Ev HOME ,
139+
.Ev TMPDIR
140+
and
141+
.Ev TMP
142+
environment variables under other operating systems can influence of the caching directory used.
143+
.Sh FILES
144+
The
145+
.Nm
146+
utility will attempt to maintain a caching directory for the web service it uses, where the downloaded database will be re-used within the next 24 hours.
147+
.Pp
148+
This directory will be located in one of the following places:
149+
.Bl -bullet
150+
.It
151+
Windows:
152+
.Bl -bullet
153+
.It
154+
.Pa %LOCALAPPDATA%/cache/vuxml
155+
.It
156+
.Pa %TMP%/cache/vuxml
157+
.El
158+
.It
159+
Unix:
160+
.Bl -bullet
161+
.It
162+
.Pa ${HOME}/.cache/vuxml
163+
.It
164+
.Pa ${TMPDIR}/.cache/vuxml
165+
.It
166+
.Pa ${TMP}/.cache/vuxml
167+
.El
168+
.El
169+
.Sh EXIT STATUS
170+
.Ex -std vuxml
171+
.Sh EXAMPLES
172+
Use the following command to search for vulnerabilities affecting the "gnutls" package:
173+
.Bd -literal
174+
vuxml -p gnutls
175+
.Ed
176+
.Pp
177+
And the following one to search for vulnerabilities affecting packages whose name starts with "gnutls" ("gnutls", "gnutls-devel", "gnutls3" will match, while "linux-f10-gnutls" won't):
178+
.Bd -literal
179+
vuxml -Rp "^gnutls"
180+
.Ed
181+
.Sh SEE ALSO
182+
.Xr vuxml 3 ,
183+
.Lk https://www.vuxml.org/ VuXML website
184+
.Lk https://www.vuxml.org/freebsd/ FreeBSD VuXML website
185+
.Lk https://docs.freebsd.org/en/books/porters-handbook/security/ VuXML database explanation in the Porter's handbook
186+
.Lk https://www.freshports.org/security/vuxml/ VuXML database as a FreeBSD port
187+
.Xr pkg-audit 8 ,
188+
.Xr vxquery
189+
.Sh STANDARDS
190+
The
191+
.Nm
192+
utility is not a standard UNIX command.
193+
.Pp
194+
It tries to follow the PEP 8 style guide for Python code.
195+
.Sh PORTABILITY
196+
Tested OK under Windows.
197+
.Sh HISTORY
198+
This implementation was made for the
199+
.Lk https://github.com/HubTou/PNU PNU project
200+
.Pp
201+
While working on the
202+
.Xr pipinfo 1
203+
tool, I noticed that some Python packages installed as FreeBSD ports
204+
where marked as vulnerable in Python advisories but not in FreeBSD ports advisories.
205+
.Pp
206+
I made a tool to check the 4000+ FreeBSD ports of Python packages, and found around 1% of them vulnerable.
207+
.Pp
208+
So I made a library in order to verify if these vulnerable ports where also marked as vulnerable in FreeBSD VuXML,
209+
and got carried away writing this utility to demonstrate the use of the library!
210+
.Sh LICENSE
211+
This utility is available under the 3-clause BSD license.
212+
.Sh AUTHORS
213+
.An Hubert Tournier
214+
.Sh CAVEATS
215+
PORTREVISION and PORTEPOCH (ie. software versions ending with "_number" or ",number")
216+
are not taken into account when checking if a vulnerable Python package is also a vulnerable FreeBSD port.
217+
I would have to develop my own versions comparison library in order to handle that (well, maybe one day :-) ).

0 commit comments

Comments
 (0)